NZ Shared Digital Health Record API
1.1.0 - release
NZ Shared Digital Health Record API
1.1.0 - release
NZ Shared Digital Health Record API - Local Development build (v1.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Draft: These compliance requirements are currently in draft and should be treated as draft content.
These compliance requirements are for any user interface that can access and display Shared Digital Health Record information to a clinical user.
API Consumers accessing and displaying records to clinical users need to periodically retrieve their verification samples from the verification sample endpoint. The samples are represented as FHIR AuditEvent resources in accordance with the SDHR AuditEvent profile.
Once retrieved, those samples need to be verified by the API Consumer using either an automated or manual process. Once access has been reviewed, the results must be submitted back to the Shared Digital Health Record to advise of the result.
The following sequence diagram provides a basic overview of the verification workflow between the API Consumer and the Shared Digital Health Record server.
These verification operations and examples are currently draft and should be treated as draft interface content.
This workflow is not a one off onboarding activity. API Consumers need to perform this retrieval and verification process periodically on an ongoing basis so that sampled access events continue to be reviewed and verified over time.
Retrieve verification samples: The Data Viewer Application calls the draft GET /AuditEvent/$verification-samples operation to retrieve a Bundle of sampled AuditEvent resources that require verification. The operation also supports _count and _offset query parameters for paging, for example GET /AuditEvent/$verification-samples?_count=1&_offset=0. See SDHRVerificationSamplesOperation.
{
"resourceType" : "Bundle",
"id" : "BundleVerificationSamplesResponseExample",
"type" : "collection",
"timestamp" : "2026-07-03T10:00:00+12:00",
"total" : 2,
"link" : [
{
"relation" : "self",
"url" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/$verification-samples"
}
],
"entry" : [
{
"fullUrl" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/b3f9de58-2da4-427c-a39c-07147eac3615",
"resource" : {
"resourceType" : "AuditEvent",
"id" : "b3f9de58-2da4-427c-a39c-07147eac3615",
"meta" : {
"profile" : [
🔗 "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAuditEvent"
]
},
"text" : {
"status" : "generated",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><a name=\"AuditEvent_b3f9de58-2da4-427c-a39c-07147eac3615\"> </a><p class=\"res-header-id\"><b>Generated Narrative: AuditEvent b3f9de58-2da4-427c-a39c-07147eac3615</b></p><a name=\"b3f9de58-2da4-427c-a39c-07147eac3615\"> </a><a name=\"hcb3f9de58-2da4-427c-a39c-07147eac3615\"> </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\"/><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-SDHRAuditEvent.html\">SDHRAuditEvent</a></p></div><p><b>type</b>: <a href=\"http://terminology.hl7.org/7.2.0/CodeSystem-audit-event-type.html#audit-event-type-rest\">Audit Event ID: rest</a> (Restful Operation)</p><p><b>subtype</b>: <a href=\"http://hl7.org/fhir/R4/codesystem-restful-interaction.html#restful-interaction-read\">FHIR Restful Interactions: read</a> (read)</p><p><b>action</b>: Read/View/Print</p><p><b>recorded</b>: 2026-07-03 09:15:00+1200</p><p><b>outcome</b>: Success</p><p><b>outcomeDesc</b>: Successful access sample returned for verification workflow.</p><h3>Agents</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Who</b></td><td><b>Requestor</b></td></tr><tr><td style=\"display: none\">*</td><td>Identifier: HPIProvider/1234</td><td>true</td></tr></table><h3>Sources</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Observer</b></td></tr><tr><td style=\"display: none\">*</td><td>HNZ API Gateway</td></tr></table><blockquote><p><b>entity</b></p><p><b>what</b>: Identifier: <code>https://standards.digital.health.nz/ns/nhi</code>/ZKC7284</p></blockquote><blockquote><p><b>entity</b></p><p><b>what</b>: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&canonical=http://fhir.org.nz/ig/base/Condition/ConditionRespiratoryExample\">Condition/ConditionRespiratoryExample</a></p><h3>Details</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Type</b></td><td><b>Value[x]</b></td></tr><tr><td style=\"display: none\">*</td><td>correlationId</td><td>c500dae6-ac65-4e4f-a4c1-5aa222a6a807</td></tr></table></blockquote></div>"
},
"type" : {
"system" : "http://terminology.hl7.org/CodeSystem/audit-event-type",
"code" : "rest",
"display" : "Restful Operation"
},
"subtype" : [
{
"system" : "http://hl7.org/fhir/restful-interaction",
"code" : "read",
"display" : "read"
}
],
"action" : "R",
"recorded" : "2026-07-03T09:15:00+12:00",
"outcome" : "0",
"outcomeDesc" : "Successful access sample returned for verification workflow.",
"agent" : [
{
"who" : {
"identifier" : {
"system" : "https://standards.digital.health.nz/ns/hpi-person-id",
"value" : "1234"
}
},
"requestor" : true
}
],
"source" : {
"observer" : {
"display" : "HNZ API Gateway"
}
},
"entity" : [
{
"what" : {
"identifier" : {
"system" : "https://standards.digital.health.nz/ns/nhi",
"value" : "ZKC7284"
}
}
},
{
"what" : {
"reference" : "Condition/ConditionRespiratoryExample"
},
"detail" : [
{
"type" : "correlationId",
"valueString" : "c500dae6-ac65-4e4f-a4c1-5aa222a6a807"
}
]
}
]
}
},
{
"fullUrl" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/6ebffb1a-61a1-4646-857e-51d4153b698d",
"resource" : {
"resourceType" : "AuditEvent",
"id" : "6ebffb1a-61a1-4646-857e-51d4153b698d",
"meta" : {
"profile" : [
🔗 "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAuditEvent"
]
},
"text" : {
"status" : "generated",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><a name=\"AuditEvent_6ebffb1a-61a1-4646-857e-51d4153b698d\"> </a><p class=\"res-header-id\"><b>Generated Narrative: AuditEvent 6ebffb1a-61a1-4646-857e-51d4153b698d</b></p><a name=\"6ebffb1a-61a1-4646-857e-51d4153b698d\"> </a><a name=\"hc6ebffb1a-61a1-4646-857e-51d4153b698d\"> </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\"/><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-SDHRAuditEvent.html\">SDHRAuditEvent</a></p></div><p><b>type</b>: <a href=\"http://terminology.hl7.org/7.2.0/CodeSystem-audit-event-type.html#audit-event-type-rest\">Audit Event ID: rest</a> (Restful Operation)</p><p><b>subtype</b>: <a href=\"http://hl7.org/fhir/R4/codesystem-restful-interaction.html#restful-interaction-search-type\">FHIR Restful Interactions: search-type</a> (search-type)</p><p><b>action</b>: Execute</p><p><b>recorded</b>: 2026-07-03 09:20:00+1200</p><p><b>outcome</b>: Success</p><p><b>outcomeDesc</b>: Successful search access sample returned for verification workflow.</p><h3>Agents</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Who</b></td><td><b>Requestor</b></td></tr><tr><td style=\"display: none\">*</td><td>Identifier: HPIProvider/1234</td><td>true</td></tr></table><h3>Sources</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Observer</b></td></tr><tr><td style=\"display: none\">*</td><td>HNZ API Gateway</td></tr></table><blockquote><p><b>entity</b></p><p><b>what</b>: Identifier: <code>https://standards.digital.health.nz/ns/nhi</code>/ZKC7284</p></blockquote><blockquote><p><b>entity</b></p><p><b>what</b>: <a href=\"AllergyIntolerance-AllergyIntoleranceExample.html\">AllergyIntolerance Allergy to penicillin (finding)</a></p><h3>Details</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Type</b></td><td><b>Value[x]</b></td></tr><tr><td style=\"display: none\">*</td><td>correlationId</td><td>c500dae6-ac65-4e4f-a4c1-5aa222a6a807</td></tr></table></blockquote></div>"
},
"type" : {
"system" : "http://terminology.hl7.org/CodeSystem/audit-event-type",
"code" : "rest",
"display" : "Restful Operation"
},
"subtype" : [
{
"system" : "http://hl7.org/fhir/restful-interaction",
"code" : "search-type",
"display" : "search-type"
}
],
"action" : "E",
"recorded" : "2026-07-03T09:20:00+12:00",
"outcome" : "0",
"outcomeDesc" : "Successful search access sample returned for verification workflow.",
"agent" : [
{
"who" : {
"identifier" : {
"system" : "https://standards.digital.health.nz/ns/hpi-person-id",
"value" : "1234"
}
},
"requestor" : true
}
],
"source" : {
"observer" : {
"display" : "HNZ API Gateway"
}
},
"entity" : [
{
"what" : {
"identifier" : {
"system" : "https://standards.digital.health.nz/ns/nhi",
"value" : "ZKC7284"
}
}
},
{
"what" : {
🔗 "reference" : "AllergyIntolerance/AllergyIntoleranceExample"
},
"detail" : [
{
"type" : "correlationId",
"valueString" : "c500dae6-ac65-4e4f-a4c1-5aa222a6a807"
}
]
}
]
}
}
]
}Review sampled access events: The API Consumer reviews the returned sampled AuditEvent resources using either an automated process or a manual workflow to determine whether the recorded access was valid.
Submit verification decisions: The Data Viewer Application calls the draft POST /AuditEvent/$verification-submissions operation with the defined Parameters payload to submit one or more verification decisions for the sampled AuditEvent resources. See SDHRVerificationSubmissionsOperation, the SDHRVerificationSubmissionParameters profile, and the SDHRVerificationSubmissionResponseParameters profile.
{
"resourceType" : "Parameters",
"id" : "ParametersVerificationSubmissionRequestExample",
"meta" : {
"profile" : [
🔗 "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRVerificationSubmissionParameters"
]
},
"parameter" : [
{
"name" : "verification",
"part" : [
{
"name" : "auditEvent",
"valueReference" : {
"reference" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/b3f9de58-2da4-427c-a39c-07147eac3615"
}
},
{
"name" : "result",
"valueCode" : "validated"
}
]
},
{
"name" : "verification",
"part" : [
{
"name" : "auditEvent",
"valueReference" : {
"reference" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/6ebffb1a-61a1-4646-857e-51d4153b698d"
}
},
{
"name" : "result",
"valueCode" : "validation-failed"
}
]
}
]
}{
"resourceType" : "Parameters",
"id" : "ParametersVerificationSubmissionResponseExample",
"meta" : {
"profile" : [
🔗 "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRVerificationSubmissionResponseParameters"
]
},
"parameter" : [
{
"name" : "verificationSubmissionResult",
"part" : [
{
"name" : "auditEvent",
"valueReference" : {
"reference" : "AuditEvent/AuditEventVerificationSampleOne"
}
},
{
"name" : "status",
"valueCode" : "processed"
}
]
},
{
"name" : "verificationSubmissionResult",
"part" : [
{
"name" : "auditEvent",
"valueReference" : {
"reference" : "AuditEvent/AuditEventVerificationSampleTwo"
}
},
{
"name" : "status",
"valueCode" : "processed"
}
]
}
]
}Repeat periodically: This process needs to be repeated periodically so that newly sampled access events continue to be reviewed and verified over time.
|
Ref |
Purpose |
Input value(s) |
Expected Outcome(s) |
Mandatory |
Types of Evidence |
|---|---|---|---|---|---|
|
Security |
|||||
|
|
Securely storage of authentication credentials used for SDHR |
N/A |
Authentication Credentials for the SDHR API are stored securely, not available to users without appropriate controls in place. |
Yes |
Documentation of authentication credential storage solution and/or controls in place to prevent inappropriate access to the credential store |
|
|
User logins to the SEHR system are performed securely |
N/A |
Users of the SEHR system have secure user accounts that only they can access allowing for confidence that the user making a request to SDHR is who they say they are |
Yes |
Documentation of user account controls, SSO, MFA etc. |
|
Accurate Requests |
|||||
|
|
HPI-Facility and Org are accurately reported to SDHR |
N/A |
Clinical users must only be able to select an HPI‑Facility or HPI‑Organisation with which they have a legitimate relationship. Where a user’s HPI‑Facility/Org is assigned directly to their account, appropriate controls must ensure its accuracy. The HPI‑Facility/Org submitted to SDHR in API requests must accurately represent the user on whose behalf the request is made. |
Yes |
Documentation of user onboarding and facility/org assignment processes, evidence of mapping from user account to request, test cases |
|
|
HPI-CPN is accurately reported to SDHR |
N/A |
Clinical users must have the correct HPI-CPN assigned to their user account so this can be submitted to SDHR. Users cannot "self-select" their HPI-CPN. |
Yes |
Documentation of user onboarding and CPN assignment process |
|
|
Capture purpose of use for every access |
N/A |
SDHR is informed of the correct clinical purpose for every request. This could be based on user selection or programatically set. |
Yes |
Purpose of Use selection or recording process details |
|
|
Enforce appropriate access restrictions to SDHR data |
N/A |
Non-clinical users cannot see any SDHR data, clinical users can only see data appropriate for their role. |
Yes |
Role definitions, permission matrices |
|
|
No local retention of SDHR clinical data |
N/A |
SDHR clinical content is not stored, cached, or logged within the SEHR system. Please Note: Clinicians can make reference to SDHR data while writing notes or documents. |
Yes |
Architecture diagrams, technical attestations |
|
|
Only make requests based on user action |
N/A |
Requests for SDHR data should only be made for the purpose of displaying data to the clinical user. Non-user initiated requests should NOT be made. |
Yes |
Documentation of requests that are made, correlation of our audit events being linked to a user action in the SEHR? |
|
Data Display |
|||||
|
|
Ensure correct record is being viewed |
N/A |
Clinical users have safe methods for ensuring the correct patient record is being viewed. This could include integration directly into the existing wider patient record within the same UI or via a launch with the patient context included, display of patient demographics from a local or nationwide source to allow patient identification. An unattached SEHR record without demographics displayed that was found based on a typed NHI is insufficient. |
UI screenshots demonstrating record selection or launching process |
|
|
|
Users are made aware of SDHR data completeness limits |
N/A |
Clinical users are made aware that SDHR data may not present the full patient record. |
Yes |
UI screenshots, terms of use, training material extracts |
|
|
Provide clear feedback when no data is found |
Empty search results from SDHR |
Informative message displayed when no records are returned. |
Yes |
UI screenshots |
|
|
Users informed of withheld records |
Information withheld outcome from SDHR |
Users are informed when records are withheld (“information withheld” indicator shown). |
Yes |
UI screenshots demonstrating withheld indicators |
|
|
Users informed of domain opt out |
Domain level opt out outcome from SDHR |
Users are informed when the patient has opted out of a health domain. |
Yes |
UI screenshots |
|
|
Users informed of global opt out |
Global level opt out outcome from SDHR |
Users are informed when the patient has globally opted out of SDHR. |
Yes |
UI screenshots |
|
|
Handle SDHR API rate limiting gracefully |
HTTP 429 response from SDHR |
User receives meaningful message; system does not repeatedly retry during rate limit window. |
Yes |
UI screenshots, test evidence showing correct handling of 429 errors |
|
|
Users informed of deceased patients |
Deceased patient indicator from SDHR |
Users are alerted that a patient is deceased. |
Yes |
UI screenshots |
|
|
Support linked NHI viewing |
SDHR response including multiple NHIs |
Viewer can display records across all NHIs linked to a consumer. |
Yes |
UI screenshots demonstrating display of linked NHI test patient |
|
|
Users informed when there are more records |
Large number of records returned from SDHR |
Users are informed when there are more records than currently displayed. This could take the form of page counts, infinite scroll or other UI indicators. |
Yes |
UI screenshots |
|
|
Prevent data truncation |
SDHR response including long text strings |
SDHR data fields are displayed without truncation or loss of meaning. |
Yes |
UI screenshots demonstrating full field rendering |
|
|
Users informed of appropriate statuses of records |
SDHR response includes records with different statuses |
Users are made aware of the status of records where appropriate to ensure they can differentiate between current and past conditions, allergies etc. This could take the form of status badges or some other indicator. |
Yes |
UI screenshots |
|
|
Avoid relying on unverified patient names |
N/A |
Patient names from SDHR are either not displayed or clearly marked as non-authortative. |
Yes |
UI screenshots |
|
|
Appropriate clinical oversight of user interface |
N/A |
Governance structure, clinical sign off |
||
|
Audit |
|||||
|
|
Maintain complete audit logs |
N/A |
Audit logs capture full traceability for every SDHR interaction in compliance with HIGG. This would include at a minimum: -SEHR User ID -HPI CPN or other identifier -Full name -IP address -Facility and Organisation user belongs to -PoU for access -The API call that was made -Timestamp of access |
Yes |
Audit log extracts |
|
Monitoring |
|||||
|
|
Enable HNZ audit and investigation |
Filtered audit datasets |
SEHR can supply filtered audit logs on request (by NHI, user, org, time). |
Yes |
Sample filtered audit extracts |
|
|
Retrieve access samples from SDHR |
SDHR accesses have been performed |
SEHR is capable of retrieving sampled SDHR data accesses via the sampling API. |
Yes |
Time of API calls so SDHR can verify call was received |
|
|
Submit proactive monitoring outcomes to SDHR |
Access samples have been retrieved |
The SEHR can determine the appropriateness of accesses to SDHR data by a clinician. SEHR can submit monitoring outcomes to SDHR via the Sampling API. |
Yes |
Time of API calls so SDHR can verify call was received. Business process/rules for determining appropriateness of SDHR data access |
|
|
Perform proactive monitoring of access |
Monthly monitoring outputs |
Regular monitoring detects inappropriate or anomalous access in compliance with HIGG. |
Yes |
Monitoring reports; attestation |
|
|
Support privacy investigations and corrective action |
Incident records |
Privacy breaches are investigated, recorded, and corrective action taken. |
Yes |
SOPs, incident register extracts - this is the content though |