NZ Shared Digital Health Record API
0.5.0 - ballot
NZ Shared Digital Health Record API
0.5.0 - ballot
NZ Shared Digital Health Record API - Local Development build (v0.5.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
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. Developers should review this to understand the available API interactions and request requirements such as the Request-Context header |
| API Artifacts | List of FHIR Artifacts for this API |
| OpenAPI Specification | Machine readable OpenAPI specification for this API |
The Shared Digital Health Record FHIR API supports the FHIR search pattern.
You can see the supported search parameters for this API in the API Capability Statement
See below for some example search queries.
This query will return all Condition resources for a given Patient and meta.source.
GET /Condition?patient=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284&_source=https://api.hip.digital.health.nz/fhir/hpi/v1/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%2Fhpi%2Fv1%2FLocation%2FF38006-B&patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2Fnhi%2Fv1%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/hpi/v1/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/nhi/v1/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/hpi/v1/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/hpi/v1/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": {
"extension": [
{
"valueBoolean": true,
"url": "http://hl7.org.nz/fhir/StructureDefinition/long-term-condition"
}
],
"recorder": {
"reference": "https://api.hip.digital.health.nz/fhir/hpi/v1/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/nhi/v1/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/hpi/v1/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/hpi/v1/Location/F38006-B"
},
"id": "c3605e85-6785-4fa9-94a5-6d8015416c53",
"resourceType": "Condition"
}
}
]
}
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
Conditionresources for a specific identifierGET Condition?patient=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284&identifier=38cb6f26-9534-46e5-b659-536992faf0cc
Request
Conditionresources for a specific identifier AND system,GET /Condition?patient=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284&identifier=https://some.local.system/ehr-key%7Cd2ed3bc7-da4a-45b8-ae3f-82176f5c64a4
{
"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%2Fnhi%2Fv1%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/hpi/v1/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/nhi/v1/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/hpi/v1/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/hpi/v1/Location/F38006-B"
},
"id": "72ca633a-23cc-4848-a512-5111750508fb",
"resourceType": "Condition"
}
}
]
}
This section describes the process of SDHR API Consumer system interacting with the SDHR FHIR server to update existing resources.
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.
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.
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}
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.
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.
When a record is created or updated to be marked as confidential using FHIR Security labels, read or search operations that would return the record will result in no access to the record.
When the data sensitivity tags using the confidentiality system http://terminology.hl7.org/CodeSystem/v3-Confidentiality are be applied to any SDHR resource, by adding the tag in the resource meta.security array, the API will use the follow behaviours when the resources are subject to FHIR API Requests.
The behaviours are valid for resources containing an security label using the http://terminology.hl7.org/CodeSystem/v3-Confidentiality system and R (Restricted) or V (Very Restricted). SDHR resources which do not contain this confidentiality tag will not be subject to these behaviours.
{
"resourceType" : "AllergyIntolerance",
"id" : "AllergyIntoleranceExample",
"meta" : {
"lastUpdated" : "2024-01-26T10:03:26+13:00",
"source" : "https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B",
"profile" : [
🔗 "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAllergyIntolerance"
],
"security" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
"code" : "R",
"display" : "Restricted"
}
]
},
"text" : {
"status" : "extensions",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: AllergyIntolerance AllergyIntoleranceExample</b></p><a name=\"AllergyIntoleranceExample\"> </a><a name=\"hcAllergyIntoleranceExample\"> </a><a name=\"AllergyIntoleranceExample-en-US\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\">Last updated: 2024-01-26 10:03:26+1300; </p><p style=\"margin-bottom: 0px\">Information Source: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&canonical=https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B\">https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B</a></p><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-SDHRAllergyIntolerance.html\">SDHRAllergyIntolerance</a></p><p style=\"margin-bottom: 0px\">Security Label: Restricted (Details: Confidentiality code R = 'Restricted')</p></div><p><b>Client Last Updated</b>: 2023-11-26 10:02:45+1300</p><p><b>identifier</b>: <code>https://fhir.examplepms.co.nz</code>/ec2d6cad-1e19-46ee-accf-dc460a680710\u00a0(use:\u00a0secondary,\u00a0)</p><p><b>clinicalStatus</b>: <span title=\"Codes:{http://snomed.info/sct 443601000210103}\">Active Phase</span></p><p><b>verificationStatus</b>: <span title=\"Codes:{http://snomed.info/sct 410605003}\">Confirmed present</span></p><p><b>type</b>: Allergy</p><p><b>category</b>: 62014003</p><p><b>code</b>: <span title=\"Codes:{http://snomed.info/sct 91936005}\">Allergy to penicillin (finding)</span></p><p><b>patient</b>: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&canonical=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284\">Sage Westbrook</a></p><p><b>recorder</b>: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&canonical=https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/91ZZXN\">DR Julian Subatoi Bashir</a></p></div>"
},
"extension" : [
{
"url" : "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/hnz-sdhr-client-last-updated-extension",
"valueDateTime" : "2023-11-26T10:02:45+13:00"
}
],
"identifier" : [
{
"use" : "secondary",
"system" : "https://fhir.examplepms.co.nz",
"value" : "ec2d6cad-1e19-46ee-accf-dc460a680710"
}
],
"clinicalStatus" : {
"coding" : [
{
"system" : "http://snomed.info/sct",
"code" : "443601000210103",
"display" : "Active Phase"
}
]
},
"verificationStatus" : {
"coding" : [
{
"system" : "http://snomed.info/sct",
"code" : "410605003",
"display" : "Confirmed present"
}
]
},
"type" : "allergy",
"category" : [
"62014003"
],
"code" : {
"coding" : [
{
"system" : "http://snomed.info/sct",
"code" : "91936005",
"display" : "Allergy to penicillin (finding)",
"userSelected" : true
}
]
},
"patient" : {
"reference" : "https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284",
"type" : "Patient",
"display" : "Sage Westbrook"
},
"recorder" : {
"reference" : "https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/91ZZXN",
"type" : "Practitioner",
"display" : "DR Julian Subatoi Bashir"
}
}GET /AllergyIntolerance?patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2Fnhi%2Fv1%2FPatient%2FZKC7284
Response status: 200
Response body:
{
"resourceType" : "Bundle",
"id" : "ConfidentialRecordsSearchResponseExample",
"meta" : {
"lastUpdated" : "2025-04-29T23:35:29.795Z",
"security" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
"code" : "redacted",
"display" : "REDACTED"
}
]
},
"type" : "searchset",
"total" : 2,
"link" : [
{
"relation" : "self",
"url" : "https://api.mock.sdhr.digital.health.nz/s2s/AllergyIntolerance?patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2Fnhi%2Fv1%2FPatient%2FZKC7284"
}
],
"entry" : [
{
"fullUrl" : "https://api.mock.sdhr.digital.health.nz/s2s/AllergyIntolerance/AllergyIntoleranceExample2",
"resource" : {
"resourceType" : "AllergyIntolerance",
"id" : "AllergyIntoleranceExample2",
"meta" : {
"lastUpdated" : "2024-01-26T10:03:26+13:00",
"source" : "https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B",
"profile" : [
🔗 "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAllergyIntolerance"
]
},
"text" : {
"status" : "generated",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><a name=\"AllergyIntolerance_AllergyIntoleranceExample2\"> </a><p class=\"res-header-id\"><b>Generated Narrative: AllergyIntolerance AllergyIntoleranceExample2</b></p><a name=\"AllergyIntoleranceExample2\"> </a><a name=\"hcAllergyIntoleranceExample2\"> </a><a name=\"AllergyIntoleranceExample2-en-US\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\">Last updated: 2024-01-26 10:03:26+1300; </p><p style=\"margin-bottom: 0px\">Information Source: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&canonical=https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B\">https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B</a></p><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-SDHRAllergyIntolerance.html\">SDHRAllergyIntolerance</a></p></div><p><b>identifier</b>: <code>https://fhir.examplepms.co.nz</code>/ec2d6cad-1e19-46ee-accf-dc460a680710\u00a0(use:\u00a0secondary,\u00a0)</p><p><b>clinicalStatus</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical active}\">Active</span></p><p><b>verificationStatus</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/allergyintolerance-verification confirmed}\">Confirmed</span></p><p><b>type</b>: Allergy</p><p><b>category</b>: 370540009</p><p><b>code</b>: <span title=\"Codes:{http://snomed.info/sct 227493005}\">Cashew nuts</span></p><p><b>patient</b>: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&canonical=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284\">Sage Westbrook</a></p><p><b>recorder</b>: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&canonical=https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/91ZZXN\">DR Julian Subatoi Bashir</a></p></div>"
},
"identifier" : [
{
"use" : "secondary",
"system" : "https://fhir.examplepms.co.nz",
"value" : "ec2d6cad-1e19-46ee-accf-dc460a680710"
}
],
"clinicalStatus" : {
"coding" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
"code" : "active",
"display" : "Active"
}
]
},
"verificationStatus" : {
"coding" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
"code" : "confirmed",
"display" : "Confirmed"
}
]
},
"type" : "allergy",
"category" : [
"370540009"
],
"code" : {
"coding" : [
{
"system" : "http://snomed.info/sct",
"code" : "227493005",
"display" : "Cashew nuts",
"userSelected" : true
}
]
},
"patient" : {
"reference" : "https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284",
"type" : "Patient",
"display" : "Sage Westbrook"
},
"recorder" : {
"reference" : "https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/91ZZXN",
"type" : "Practitioner",
"display" : "DR Julian Subatoi Bashir"
}
},
"search" : {
"mode" : "match"
}
}
]
}In this request example, a request is made to return AllergyIntolerance resources for a patient using FHIR Search. As a confidential resource was matched with this search, the search result set has been redacted due to confidentiality tags on the resource, resulting in the meta.security REDACTED tag being added to the search result Bundle. This indicates to the API Consumer that some portion of the searchset has been filtered due to confidentiality and not included in the content returned. The total within the response reflects the total of resources before filtering occurs.
GET /AllergyIntolerance/{id}
Response status: 403
Response body:
{
"resourceType" : "OperationOutcome",
"id" : "APIError-Confidential",
"text" : {
"status" : "generated",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: OperationOutcome APIError-Confidential</b></p><a name=\"APIError-Confidential\"> </a><a name=\"hcAPIError-Confidential\"> </a><a name=\"APIError-Confidential-en-US\"> </a><h3>Issues</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Severity</b></td><td><b>Code</b></td><td><b>Diagnostics</b></td></tr><tr><td style=\"display: none\">*</td><td>Error</td><td>Security Problem</td><td>Resource access is forbidden</td></tr></table></div>"
},
"issue" : [
{
"severity" : "error",
"code" : "security",
"diagnostics" : "Resource access is forbidden"
}
]
}In this example, a request is made to a single resource which contains a confidentiality flag. This returns a 403 error.