NZ Shared Digital Health Record API Capability Statement

Records independent domain participation choices for one patient through authorised Health NZ channels. POST a FHIR Parameters resource to https://api.sdhr.digital.health.nz/s2s/$hnz-domain-participate with exactly one patient parameter and exactly one domains parameter. The domains parameter contains one or more named boolean parts: SDHRMedications and/or SDHRImmunisations. Each domain may occur only once. A single-domain update uses the same structure with one part.

true records an explicit permit and false records a deny. Omitted domains retain their existing choices; a domain without a recorded choice defaults to In. MedicationRequest and MedicationDispense share the Medications choice. Immunisations are controlled independently.

Only the requested patient's Consent is updated. Consents for linked NHIs remain unchanged. For access, a deny on any linked NHI denies that domain for the entire linked group. Opting one patient back in cannot override another linked patient's deny. A global opt-out continues to take precedence over domain permits.

This operation does not change global or facility participation, archive or restore resources, trigger a historic load, or update participation in an upstream national system. Global participation remains managed through $hnz-participate. Global participation indicators, facility parameters, repeated patients, the singular domain parameter and repeated domainParticipation groups are not accepted by this operation.

The operation is idempotent and returns an OperationOutcome. See one-domain update and multiple-domain update.

This operation allows a patient to choose to participate in the Shared Digital Health Record service via HNZ assisted channels. This operation should only be used by HNZ channels.

Scenarios where this operation might be used include:

• A patient has opted in to the Shared Digital Health Record service by contacting Health NZ via appropriate digital or assisted channels.
• A linked group of patients has opted in to the Shared Digital Health Record service by contacting Health NZ via appropriate digital or assisted channels.
• A patient chooses not to participate in the Shared Digital Health Record service and informs Health NZ of this choice via appropriate digital or assisted channels.

For example payloads that might be used with this operation see:

• Parameters resource for total non-participation (patient choice) : This example shows a global opt-out using reason patient-choice.
• Parameters resource for total non-participation (patient deceased) : This example shows a global opt-out using reason patient-deceased.
• Parameters resource for total non-participation (imported external consent) : This example shows a global opt-out using reason imported-external-consent.
• Parameters resource for participation : This example shows how to indicate that a patient wishes to participate in the Shared Digital Health Record service.
• Parameters resource for linked group participation : This example shows how to indicate that all patients in a linked NHI group wish to participate in the Shared Digital Health Record service.

To make a request to this operation the API Consumer must POST a Parameters payload to the operation URL (e.g. POST https://api.sdhr.digital.health.nz/s2s/$hnz-participate).

The operation is idempotent, meaning that multiple requests with the same parameters will have the same effect as a single request. The operation is expected to be called by a Health NZ channel system on behalf of the patient, and the patient must be identified by their NHI. For a global opt-in request, one or more patient parameters may be supplied. Multiple patient parameters are only supported when all supplied NHIs are already linked in the same NHI group and the request supplies the complete linked group. Multiple patient parameters are not supported for global opt-out requests. When hnzParticipationIndicator is false, SDHR records the global opt-out reason (hnzOptOutReasonCode) and archives the patient's active contributed resources across all facilities. Archived resources are not returned by normal search or read interactions. When the recorded reason is patient-deceased, subsequent resource read or search requests rejected by the global consent check return HTTP 403 with the deceased global-denial OperationOutcome: "Patient data is unavailable in the Shared Digital Health Record as they are deceased." This is not the response to a successful $hnz-participate request; see global participation denial API behaviour. For a global opt-in request where the patient is enrolled with a provider, the request may include the enrolled provider facilityId and must then include pmsIdentifier. Sourcing from this facility requires the patient to be already opted in at that facility. If the facility preference is absent or opted out, global opt-in still succeeds without sourcing records, changing facility participation, or locking that facility. When sourcing is eligible, a historic load is scheduled only for pull-based acquisition. Other acquisition methods use an enrolment-data email instead. If facilityId is omitted, pmsIdentifier must also be omitted and no historic load is scheduled. When a historic load is scheduled, the returned OperationOutcome includes the informational sdhr-historic-load-scheduled issue. This confirms scheduling, not successful completion. The issue is absent when no load is scheduled, including an unchanged repeated request. See historic-load scheduling outcome. The operation will return an OperationOutcome resource indicating the result of the operation.

This internal use operation retrieves a patient's Shared Digital Health Record participation status and returns whether the patient is participating in the service, whether enrolment information was found, whether the patient has active, archived, or any records available in the service, and the opt-out reason when the patient is globally opted out.

For example response payloads for this operation see:

• Parameters resource for participation status response - not participating : No consent, enrolment, or records found for the patient.
• Parameters resource for participation status response - opted out with archived records : The enrolled patient is not currently participating and has archived records from before the opt-out.
• Parameters resource for participation status response - actively participating : Patient is actively participating with active records at a facility.
• Parameters resource for participation status response - actively participating with enrolment : Patient is actively participating with enrolment information and facility-level participation details.

To make a request to this operation the API Consumer must POST a Parameters payload to the operation URL (e.g. POST https://api.sdhr.digital.health.nz/s2s/$hnz-participation-status).

The operation will return a Parameters resource containing the patient reference, participation status indicators, and the global opt-out reason when the patient is globally opted out.

This operation allows a patient to choose to participate in the Shared Digital Health Record service. This operation should be used by data providers in the Shared Digital Health Record ecosystem such as Patient Management Systems (PMS) or Electronic Health Record (EHR) systems. It can be used to indicate whether the patient wishes to participate, whether any resources are withheld, and the reason for participation. The scope of this operation is the API consumer - e.g. an HPI Facility where patient data is held.

Scenarios where this operation might be used include:

• A patient has opted in to the Shared Digital Health Record service and appropriate data will be shared from the data holder to the service.
• A patient chooses not to participate in the Shared Digital Health Record service and informs their healthcare provider of this choice.
• A patient has one or more confidential records, held at their healthcare provider, that are withheld from the service.
• A patient has previously withheld records but has now released them to the Shared Digital Health Record service.

For example payloads that might be used with this operation see:

• Parameters resource for total non-participation : This example shows how to indicate that a patient does not wish to participate in the Shared Digital Health Record service (has opted out).
• Parameters resource for participation : This example shows how to indicate that a patient wishes to participate in the Shared Digital Health Record service, where previously opted out (opt-in).
• Parameters resource for partial participation with withheld records : This example shows how to indicate that a patient has some confidential records that are withheld from the Shared Digital Health Record service.
• Parameters resource for releasing withheld records : This example shows how to indicate that a patient has previously withheld records but has now released them to the Shared Digital Health Record service.

To make a request to this operation the API Consumer must POST a Parameters payload to the operation URL (e.g. POST https://api.sdhr.digital.health.nz/s2s/$participate).

The operation is idempotent, meaning that multiple requests with the same parameters will have the same effect as a single request. The operation is expected to be called by a healthcare provider on behalf of the patient, and the patient must be identified by their NHI. When participationIndicator is false, SDHR records the facility opt-out and archives the patient's active contributed resources from the supplied facility. Archived resources are not returned by normal search or read interactions. For an opt-in request using pull-based acquisition, the PMS may set enrolledPatient to true to indicate that the patient is enrolled at the supplied facility and that a historic load should be triggered. If enrolledPatient is omitted, the API updates consent without triggering a historic load. When a historic load is scheduled, the returned OperationOutcome includes the informational sdhr-historic-load-scheduled issue. This confirms scheduling, not successful completion. The issue is absent when no load is scheduled, including an unchanged repeated request. See historic-load scheduling outcome. The operation will return an OperationOutcome resource indicating the result of the operation.

This operation allows Shared Electronic Health Record (SEHR) systems to retrieve a patient's Shared Digital Health Record participation status.

To make a request to this operation the API Consumer must POST a Parameters payload to the operation URL (e.g. POST https://api.sdhr.digital.health.nz/s2s/$participation-status).

For an example request payload, see:

• Parameters resource for participation status request : This example shows the Parameters resource to POST to this operation.

For example response payloads for this operation see:

• Parameters resource for participation status response - not participating : This example shows the Parameters resource returned when the patient is not participating in the Shared Digital Health Record service.
• Parameters resource for participation status response - participating : This example shows the Parameters resource returned when the patient is participating in the Shared Digital Health Record service.
• OperationOutcome for invalid patient reference : This example shows the OperationOutcome returned when the patient reference does not match the required NHI Patient URL format.

The operation is expected to be called by a healthcare provider on behalf of the patient, and the patient must be identified by their NHI. This operation requires the SMART on FHIR scope https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRParticipationStatusOperation. The operation returns a Parameters resource containing only hnzParticipationIndicator. A patient with no recorded global participation preference is considered to be participating and returns true. If the patient reference is invalid, the operation returns a 400 response with an OperationOutcome carrying the sdhr-invalid-patient outcome code.

DRAFT OPERATION: This operation returns AuditEvent resources that have been sampled for verification and are still outstanding for the data viewer application.

The operation is invoked on the AuditEvent type using GET /AuditEvent/$verification-samples.

Sampling runs independently of this retrieval operation.

A successful response is always a searchset Bundle containing slim SDHRAuditEvent samples. In each sample, the application agent has the dataprocessor role and identifies the Keycloak client UUID in who.identifier. The separate healthworker agent carries the clinician’s HPI person identifier; an organisation agent may also be present. Use the clinician identity, patient NHI and recorded time to assess whether the clinician had a valid reason to access that patient. NHI and correlation ID are returned as string-valued entity.detail entries with types nhi and correlationId.

Samples:

• are pending verification
• belong to the authenticated client_id
• have not already been marked as verified by the data viewer application

The operation supports optional paging parameters:

• _count to limit the maximum number of samples returned in a single response
• _getpagesoffset to skip a number of matching samples before returning results

Only these paging parameters are forwarded to the sample search. The server fixes the client and pending-verification filters. Follow the returned paging links, which point back to this operation; links may be relative in the development environment. An empty searchset Bundle means no pending samples are currently available.

The required operation scope is https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRVerificationSamplesOperation. Generic AuditEvent read, search and write routes are unavailable.

DRAFT OPERATION: This operation allows the data viewer application to submit one or more verification decisions for previously issued AuditEvent samples.

The operation is invoked on the AuditEvent type using POST /AuditEvent/$verification-submissions with a Parameters resource in the request body.

Each repeating verification parameter identifies an AuditEvent sample and the verification result being submitted for that sample. A request may contain 1 to 100 verification parameters; requests above this limit are rejected before any decisions are processed.

The required operation scope is https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRVerificationSubmissionsOperation. References may be relative (AuditEvent/{id}) or absolute HTTP(S) URLs ending in /AuditEvent/{id}; the logical ID identifies a local sample. Versioned references, query strings and fragments are not accepted.

Each item is processed independently, in request order. Accepted result codes are validated and validation-failed; both mark a pending sample as verified and remove it from subsequent sample responses. The response contains one verificationSubmissionResult per submitted verification, with the submitted reference and a status from the SDHR Verification Submission Status CodeSystem.

A failure for one item does not stop the remaining items. An invalid Parameters envelope, no verification items, or more than 100 verification items causes a request-level error.

Search by the ClientLastUpdated extension on SDHR AllergyIntolerance resources

Search by the ClientLastUpdated extension on SDHR Condition resources

Search for conditions flagged as highlighted in the SDHRCondition profile

Search for conditions marked as long term in the SDHRCondition profile

Search by the ClientLastUpdated extension on SDHR Observation resources

This is the AIR Immunization Profile, to be used for immunisation records inbound to ImmSoT. It includes a number of constraints designed to enforce ImmSoT's lean data model approach.

SDHR allows Bundle posts with the following restrictions:

• The Bundle type must be batch (transactions are not supported).
• All Patient references in the Bundle must target a single Patient.
• The Bundle must not contain any $participate, $hnz-participate or $hnz-domain-participate requests.

Medication Dispense resource for use in NZ e-Prescription Service Medicines Data Repository

Medication Request resource for use in NZ e-Prescription Service Medications Data Repository

AllergyIntolerance FHIR resource for Shared Digital Health Record

AuditEvent returned by the SDHR verification samples operation. Contains the local verification reference, original agents, NHI and correlation ID with the minimal required FHIR AuditEvent envelope.

Condition resource to record problems and conditions affecting a person

Consent resource created to reflect a patient's preferences with regard to sharing their information with authorised health workers via the shared digital health record service. Note that this is a protected resource and scopes required to manage this resource are not provisioned to most API consumers. Facility participation preferences are managed by the Participate Operation. Health NZ channels manage global choices through HNZ Participate and independent domain choices through HNZ Domain Participate. For more details on the participate operation see SDHR Custom Operations.

Immunization resource for the Shared Digital Health Record. This profile constrains AIR Immunization content to the subset required for direct clinical care.

DRAFT PROFILE: MedicationDispense resource for Shared Digital Health Record. This profile constrains MedicationDispense to the SDHR subset of MDR medication dispense content.

DRAFT PROFILE: MedicationRequest resource for Shared Digital Health Record. This profile constrains MedicationRequest to the SDHR subset of MDR medication request content.

A Shared Digital Health Record Observation.

Parameters profile for AuditEvent verification submission payloads.

Parameters profile for AuditEvent verification submission response payloads. One result is returned per submitted verification, in request order. Invalid items may have no usable AuditEvent reference.

This extension to the AIR Immunization profile pre-adopts the FHIR R5 construct of the same name. In AIR, the (mandatory) vaccineCode element should be used to transmit a CVX or NZVX code for the vaccine, while the (optional) administeredProduct element should be used to transmit an NZMT TPUU code fot he vaccine.

This extension calculates the patient age when a vaccination was administered. Although this could be calculated by the client based on patient date of birth, it is provided as a convenience.

This extension is used in AIR to record the user who created the immunisation event record.

This extension is used in AIR to record the system or software used to create the immunisation event record. Example values are ISM, PMS, and so on.

This extension is used in AIR to record the user who modified the immunisation event or patient record.

This extension is used in AIR to record the system or software used to update the immunisation event or patient record. Example values are ISM, PMS, and so on.

This extension is to be used for communicating related person info in an AIR Immunisation Event. It holds the information transmitted in the HL7v2 NK1 segment.

This extension is used on an AIR Immunization resource that is sent to AIR as part of a $bulk-update operation. It holds the date to which the Immunisation Event has been rescheduled.

This extension allows an AIR Immunization instance to contain information from a serology report that describes a patient's expected level of immune protection from Hepatitis B infection. Note that this extension could be updated to cover additional diseases in the future.

Extension to record the last time a resource was updated by the source system. When consuming applications are writing data to the SDHR API they can use this extension to record the LastUpdated timestamp in their system

The data quality assessment of this immunization record as calculated by AIR rules.

When this recorded domain choice last changed. Metadata only; not an effective date.

Indicates whether the patient has opted out or opted in to participation at the facility. If opted out, no records will be shared from that facility.

Records the reason for an HNZ global opt-off decision.

Extension to indicate that a resource should be highlighted in the user interface. This is used to indicate that the resource is important and should be highlighted in a user interface.

Immunization Diluent

Immunization Facility Mobile Site

NZePS item status returned alongside MedicationRequest.status. For active prescriptions it may indicate whether repeats remain; SDHR status filtering uses MedicationRequest.status.

NZ Pharmacy Claim Number.

NZePS Patients Instructions modification indicator

NZePS medication modification indicator

Status Type of a NZ ePrescription (NZePS)

The match of a planned event to an immunisation event as calculated by AIR rules.

The match quality of a planned event to an immunisation event as calculated by AIR rules.

Supported SDHR domain participation identifiers.

A ValueSet containing all codes from the AllergyIntolerance Code system.

A ValueSet containing all codes from the AllergyIntolerance Manifestation system.

A ValueSet containing all codes from the AllergyIntolerance Severity system.

A ValueSet containing the allowed reasons for HNZ global opt-off.

A ValueSet containing all codes from the SDHR Participation Reason system.

A ValueSet containing all codes from the SDHR Resource Tags system.

A ValueSet containing all codes from the SDHR Verification Result system.

Allowed statuses for individual AuditEvent verification submission responses.

This code system defines the reasons for an HNZ global opt-off decision.

This system defines standard codes used throughout this Implementation Guide for New Zealand Shared Digital Health Records

This code system is used when the appropriate code is not known or can not be determined.

National data domains supporting independent SDHR participation choices.

This code system defines the reasons for a patient to participate in the Shared Digital Health Record service.

This code system defines standard OperationOucome codes used throughout this Implementation Guide for New Zealand Shared Digital Health Records

This code system defines the result codes used when a data viewer application submits verification decisions for sampled AuditEvent resources.

Status codes returned for individual AuditEvent verification submissions.

Example OperationOutcome API response, returned when a resource has been flagged as confidential, and so cannot be accessed.

Access to Shared Digital Health Records is restricted.<br> This API validates information that is provided by the API Consumer in their Request-Context header. The API Consumer must also provide an appropriate OAuth 2.0 Bearer token in the Authorization header containing scopes appropriate for the resource being accessed. The API Consumer must be registered with the Shared Digital Health Record API.

An example payload for a Primary Care AllergyIntolerance resource indicating an allergy to Penicillin, with a confidentiality of restricted.

An example payload for a Primary Care AllergyIntolerance resource indicating an allergy to Cashew nuts

Sampled AuditEvent returned for verification.

Sampled AuditEvent returned for verification.

Search Bundle returned for the authenticated client when no samples are pending verification.

First page Bundle returned from the verification samples operation using _count and _getpagesoffset.

Second page Bundle returned from the verification samples operation using _count and _getpagesoffset.

Bundle returned from the verification samples operation.

Example Hypertension Condition

Example Respiratory Condition

Technical stub resources so absolute references to the HIP FHIR server (NHI/HPI) resolve during IG validation. Not real API payloads used by SDHR.

An example SDHR Vital Signs Observation

HTTP 403 response for SDHR domain Opt-off or AIR Restricted Access.

Example OperationOutcome for a request where the patient has opted out of participating in the shared digital health record service for a specific facility.

This outcome message will be returned in a special case where a facility has been locked due to a background load process where the SDHR service is performing a historic record load for a practice. A typical scenario where this would occur would be where a practice has 'onboarded' to the SDHR service and SDHR is sourcing historic records for consented patients. If a data holder receives this outcome when loading records they should queue the failed records and retry after a delay.

This outcome message will be returned where a facility is not yet onboarded to SDHR.

Example OperationOutcome for a read or search request denied by a global opt-out with reason patient-deceased.

Example OperationOutcome for a request where the patient has opted out of participating in the shared digital health record service.

Medication search warning when any facility opt-out exists, including when no records were removed from the response.

Example OperationOutcome for an invalid patient participation operation indicating that the patient parameter is invalid.

Successful participation response when a historic load has been scheduled for pull-based acquisition. Scheduling does not confirm completion.

Example OperationOutcome for a missing reason code in the Participate operation indicating that the reason for participation status is required.

Example OperationOutcome where a patient has not indicated their participation preferences for the Shared Digital Health Record service.

Example OperationOutcome for a successful participation operation indicating that the patient's participation status was successfully recorded.

Example OperationOutcome for an invalid patient reference in the participation status operation.

This outcome message will be returned in a special case where a patient record has been locked due to a background load process where the SDHR service is performing a historic record load for a patient. A typical scenario where this would occur would be where a practice has 'onboarded' to the SDHR service and SDHR is sourcing historic records for a patient who has contented to participation. If a data holder receives this outcome when loading records they should queue the failed record(s) and retry after a delay.

This outcome message will be returned where an API Consumer has exceeded the allocated rate limit.

Example OperationOutcome when a patient has withheld records at source.

Example parameters content to POST to the Participate operation where a patient does not wish to participate in the Shared Digital Health Record service.

A request to $hnz-domain-participate that denies Medications and permits Immunisations on one patient's Consent.

A one-domain request to $hnz-domain-participate. Other domain choices remain unchanged.

Example parameters content to POST to the HNZ Participate ($hnz-participate) operation where all patients in a linked NHI group elect to participate in the Shared Digital Health Record service by using an appropriate HNZ digital or assisted channel.

Example parameters content to POST to the HNZ Participate ($hnz-participate) operation where a patient elects to participate in the Shared Digital Health Record service by using an appropriate HNZ digital or assisted channel.

Example parameters content to POST to the HNZ Participate ($hnz-participate) operation where a patient elects not to participate in the Shared Digital Health Record service by using an appropriate HNZ digital or assisted channel.

Example parameters content to POST to the HNZ Participate ($hnz-participate) operation where global opt-out is recorded because the patient is deceased.

Example parameters content to POST to the HNZ Participate ($hnz-participate) operation where global opt-out is imported from an external consent source.

Example parameters content to POST to the Participate operation where a patient wishes to participate in the Shared Digital Health Record service.

Example parameters content to POST to the Participate operation where a patient has individual records that are no longer withheld.

Example parameters content to POST to the Participate operation where a patient has individual records that are withheld - e.g. records marked as Confidential.

Example parameters content returned by the Participation Status operation when a patient is actively participating in the Shared Digital Health Record service with active records at a specific facility.

Example parameters content returned by the Participation Status operation when a patient is actively participating with enrolment information, including facility-level participation details for both their enrolled facility and all other facilities where they have an explicit participation record.

Example parameters content returned by the Participation Status operation after an enrolled patient opts out and their previously active records are archived.

Example parameters content returned by the Participation Status operation when the patient is not participating in the Shared Digital Health Record service.

Example parameters content returned by the Participation Status operation when the patient is participating in the Shared Digital Health Record service.

Example Parameters resource to POST to the Participation Status operation.

Example parameters content returned by the Participation Status operation when no participation enrolment or records are found for a patient.

Response when the submission request example is repeated after both decisions have been processed. Each reference is echoed unchanged and each sample returns already-processed, including the sample whose result was validation-failed. The saved decisions are unchanged.

Parameters payload posted to the verification submissions operation.

Parameters response returned from the verification submissions operation.

Example of a search response for a condition search. In this case the search response returns one result using the search parameters code and subject. GET /Condition?subject=https://api.hip.digital.health.nz/fhir/Patient/ZKC7284&code=http://snomed.info/sct%7C38341003

Example of a searchset API response for an AllergyIntolerance resource search. In this case, the search response returns one entry item, with a total count of 2. This is because the API will not return the confidential record. The redacted security label is applied to the Bundle response, to indicate that confidential records have been removed from the result set. See the API documentation for more information.

Example of a searchset API response for an Condition resource search where the patient has withheld records at their PMS. In this case, the server does not have the record but the parameters supplied in the search mean we are able to uniquely match to a single record that has been withheld using the $participate operation. The search response returns zero entries 'total':0. The response includes an entry which is an OperationOutcome resource indicating that records were withheld at source. This is indicated by the search.mode being set to outcome for the OperationOutcome entry.

Example of a searchset API response for an Condition resource search where the patient has withheld records at their PMS. In this case, the search response returns one entry 'total':1. The response also includes an entry which is an OperationOutcome resource indicating that some records were withheld at source. This is indicated by the search.mode being set to outcome for the OperationOutcome entry.