NZ Shared Digital Health Record API
1.1.6 - release

NZ Shared Digital Health Record API, published by Health New Zealand. This guide is not an authorized publication; it is the continuous build for version 1.1.6 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/tewhatuora/fhir-sdhr/ and changes regularly. See the Directory of published versions

Access Information from SDHR

Draft: This page is subject to change and will be updated as the access workflow and associated assurance requirements are confirmed.

Purpose and scope

To allow SEHR systems and other clinical portal applications to retrieve patient health information from SDHR and make it available to healthcare professionals involved in providing care.

Actors

Actor Role
Healthcare professional Uses information in the context of providing care to a specific patient.
SEHR system Identifies the patient, supplies the required access context, requests information, and presents the response.
SDHR Applies applicable controls, audits access, and returns information the requester is authorised to access.
Source systems Originate information made available through SDHR.

Scope

This use case currently or progressively applies to:

The corresponding FHIR representations are described in data models and FHIR artifacts.

Business rules

  • Requests must include sufficient context to support audit and access review.
  • The accessing system may check the patient's global SDHR participation status before requesting or presenting SDHR health information.
  • Patient participation and privacy controls must be applied before information is returned.
  • Confidential or restricted information must only be returned where permitted.
  • Accessing systems must present SDHR information in a way that supports safe clinical interpretation.
  • Accessing systems should make source, date, status, and relevant limitations visible where these affect interpretation.
  • Accessing systems must comply with the requirements for systems reading SDHR information.
  • Accessing systems must not imply that absence of information in SDHR means absence of a clinical condition, medication, allergy, observation, immunisation, or other relevant health information.
  • SDHR does not manage end-user accounts for accessing systems. Accessing systems are responsible for authenticating users and applying role-based access controls that are appropriate for their local environment and permitted use of SDHR information.

Required request context

All requests for SDHR information must include sufficient context to support audit, monitoring, privacy investigation, appropriate-use review, and assurance activities.

At a minimum, requests are expected to provide:

  • user identifier
  • user name
  • user role
  • organisation identifier
  • facility identifier
  • purpose of use
  • patient context

Requests that do not include valid request context may be rejected and no information may be returned.

The detailed structure, validation rules, and technical implementation of request context are described in the Authentication and Request Context documentation and API Capability Statement.

Preconditions

  • The accessing system has completed onboarding and required compliance activities.
  • The accessing system is authorised to access SDHR.
  • The healthcare professional is authenticated.
  • The request is made in the context of a specific patient.
  • The patient can be identified, normally using NHI.
  • The accessing system may optionally have checked the patient's global participation status using the $participation-status operation.
  • Patient participation, privacy, confidentiality, security, and access controls permit information to be returned.
  • The request includes required user, organisation, facility, and request context for audit purposes, where applicable.

Access information

Access workflow

SDHR Information Access Sequence DiagramSDHR Information Access Sequence DiagramHealth PractitionerSEHRSDHR FHIR APISDHR Primary CareNational HealthHealth PractitionerHealth PractitionerSEHRSEHRSDHR FHIR APISDHR FHIR APISDHR Primary CareCollectionSDHR Primary CareCollectionNational HealthInformation SourceNational HealthInformation Source[01]Select patient and request information[02]Establish patient, user,organisation, and facility contextopt[Check global participation status][03]Check global participationPOST /$participation-status[04]Authorise and audit request[05]Return Parameters withhnzParticipationIndicator[06]Search or read patient informationwith required access context[07]Authorise and audit request[08]Apply participation, privacy,confidentiality, and access controlsalt[Primary care information requested][09]Retrieve permitted records[10]Return available records[National information requested][11]Retrieve permitted information[12]Return available informationalt[Request completed][13]Return FHIR Bundle or resource[14]Retain required audit and source context[15]Present information safely[Request cannot be completed][16]Return error outcome[17]Handle error explicitly

Processing steps

  1. A healthcare professional selects a specific patient in the SEHR.
  2. The SEHR establishes the patient, authenticated user, organisation, facility, and request context required for access and audit.
  3. The SEHR may call the $participation-status operation with the patient's NHI to check global participation.
  4. If hnzParticipationIndicator is true, the SEHR uses a supported search or read interaction to request relevant information from SDHR. If it is false, the SEHR stops the information workflow and does not present SDHR clinical information.
  5. SDHR authorises and audits the request and applies applicable participation, privacy, confidentiality, security, and access controls.
  6. SDHR retrieves permitted information from the SDHR Primary Care Collection or an applicable national health information source.
  7. SDHR returns authorised FHIR resources, an empty or filtered result, or an error outcome as applicable.
  8. The SEHR retains required local audit and traceability information.
  9. The SEHR presents source, date, status, and relevant limitations in a clinically safe and usable way.

Key behaviour

  • The healthcare professional uses an SEHR.
  • The SEHR identifies the patient and requests relevant information from SDHR.
  • The SEHR can check global participation before requesting information and uses hnzParticipationIndicator to determine whether to continue.
  • SDHR applies applicable privacy, participation, confidentiality, security, and access controls.
  • SDHR returns information the requester is authorised to access.
  • The SEHR presents the information to the healthcare professional in a clinically safe and usable way.

Response and error handling

  • A successful search returns a FHIR Bundle; a successful read returns the requested resource.
  • A successful $participation-status request returns a FHIR Parameters resource containing only hnzParticipationIndicator. A patient with no recorded global preference returns true.
  • If hnzParticipationIndicator is false, the SEHR must treat the patient as globally opted out and indicate this to the end user.
  • An empty result may mean that SDHR has no matching information available to the requester. It must not be presented as proof that the clinical information does not exist.
  • Patient identity should be established using local or authoritative identity services. Patient names returned with SDHR information should not be treated as the authoritative source of patient identity.
  • A filtered result may contain metadata indicating that confidentiality controls, participation settings, source-system restrictions, or other information-sharing controls have removed information from the response.
  • Accessing systems must not assume that all relevant information has been returned when filtering controls have been applied.
  • Invalid, unauthorised, or prohibited requests return an error outcome that the SEHR must handle explicitly.
  • Detailed response behaviour, status codes, payloads, and errors are documented in the API documentation.

Important SDHR access outcomes

In some circumstances SDHR may return responses indicating that information cannot be returned or that information has been intentionally omitted due to participation, privacy, confidentiality, or operational controls.

Accessing systems should identify these responses and communicate them clearly to users in a clinically safe manner.

Examples include:

Scenario Meaning
Patient does not participate in SDHR The patient has chosen not to participate in the Shared Digital Health Record service.
Information withheld at source Information may have been withheld by the source system according to patient preferences or source-system rules.
Information type not shared The patient has chosen not to share a particular type of information.
Deceased patient A read or search rejected by a global opt-out with reason patient-deceased returns HTTP 403 and code sdhr-participation-status-denied-deceased. See the deceased global-denial example.
Temporary record lock Information is temporarily unavailable while background processing is occurring.
Technical access limits The request could not be completed because a technical usage limit was reached.

Implementers should use the coded response supplied by SDHR when determining how to handle these situations rather than relying solely on displayed message text.

The detailed response structures and operation outcomes are described in the API documentation.

For deceased global denial, the response message is "Patient data is unavailable in the Shared Digital Health Record as they are deceased." This reflects the recorded global opt-out reason, not a new deceased-status lookup. See global participation denial API behaviour.

Audit and user context

Access to SDHR information must be attributable to an authenticated healthcare professional or other authorised user and an authorised organisation or facility. Access must occur in the context of a specific patient. Accessing systems must provide sufficient user and request context to support audit, monitoring, privacy investigation, appropriate-use review, and assurance activities.

Audit access records workflow

The access-verification workflow is draft and subject to change.

SDHR Audit Access Records Sequence DiagramSDHR Audit Access Records Sequence DiagramHealth PractitionerSEHRSDHR FHIR APISDHR SamplerHealth PractitionerHealth PractitionerSEHRSEHRSDHR FHIR APISDHR FHIR APISDHR SamplerSDHR SamplerRecord access[01]Select patient and request information[02]Record user action and request contextin local audit record[03]Search or read patient informationwith required access context[04]Authorise and audit request[05]Record access event[06]Return FHIR response or error outcome[07]Correlate response with local audit recordSample access records independently[08]Sample access events for eligible systemsVerify sampled access recordsloop[Ongoing access verification][09]GET /AuditEvent/$verification-samples[10]Identify eligible outstanding samples[11]Searchset Bundle of sampled AuditEventresourcesEmpty when no samples are pending[12]Review each sample using anautomated or manual process[13]POST /AuditEvent/$verification-submissionsParameters with verification decisions[14]Parameters with processing results

Audit processing steps

  1. The SEHR records the user action and the context associated with each request to access SDHR information.
  2. The SEHR sends the request to SDHR with the required access context.
  3. SDHR authorises and audits the request and records the resulting access event.
  4. The SEHR correlates the response with its local audit record.
  5. Periodically, the SEHR retrieves sampled SDHR access events that require verification.
  6. The SEHR reviews each sampled AuditEvent using an automated or manual process to determine whether the access was valid.
  7. The SEHR submits the verification decisions to SDHR and receives the processing results.
  8. The SEHR repeats the verification workflow so newly sampled access events continue to be reviewed.

Access verification is a required assurance activity for systems accessing SDHR information. Accessing systems are expected to periodically retrieve sampled access events, assess whether the access was appropriate, and submit verification outcomes back to SDHR.

SDHR requests a sample for each eligible system from the preceding 24-hour window. Several agent entries are provided: the application agent identifies the requesting client UUID, the separate healthworker agent identifies the clinician by HPI person identifier, and an organisation agent may also be present. The verifying system then checks the clinician identity and patient NHI to assess whether that clinician had a valid reason to access that patient’s information. Sampling runs independently of retrieval requests. Successful retrieval requests always return a searchset Bundle, including an empty Bundle when no samples are pending.

This process supports ongoing monitoring, auditing, and assurance activities.

The SEHR is also responsible for maintaining appropriate local audit and traceability where required.

See the API Capability Statement for request-context mechanics, the API documentation for access verification operations, and the compliance requirements for systems reading data.

Interaction Use in this workflow API documentation
Global participation status Check whether the patient is globally participating before requesting health information. Participation status operation
Search and read — contributed information Retrieve information stored in the SDHR Primary Care Collection. Contributed resource interactions
Search and read — national information Retrieve information made available from supported national health information sources. National source resource interactions
Request context Attribute access to the user, organisation, facility, and patient context. Authentication and request context
Access verification Review sampled access events and submit verification decisions. Access verification operations
Filtered and empty results Handle confidentiality filtering without inferring that no clinical information exists. Confidential record API behaviour
Errors Handle authentication, validation, access, and request errors. Authentication and request-context error example