NZ Shared Digital Health Record API Capability Statement

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 : 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.
• 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. For a global opt-in request where the patient is enrolled with a provider, the request may include the enrolled provider facilityId and must include pmsIdentifier. If facilityId is not provided, pmsIdentifier must not be provided and the operation updates consent without triggering a historic load. The operation will return an OperationOutcome resource indicating the result of the operation.

This operation retrieves a patient's Shared Digital Health Record participation status. 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 returns whether the patient is participating in the service, whether enrolment information was found, and whether the patient has active, archived, or any records available in the service. The scope of the status returned is the API consumer, for example an HPI Facility where patient data is held.

For an example response payload 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 - enrolment found, not participating : Enrolment information is found but the patient is not currently participating.
• 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 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. The operation will return a Parameters resource containing the patient reference and participation status indicators.

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. For an opt-in request, a Medtech 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 treats the caller as non-Medtech or unknown and updates consent without triggering a historic load. The operation will return an OperationOutcome resource indicating the result of the operation.

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.

The response is a Bundle containing sampled AuditEvent resources that:

• are pending verification
• are eligible for the authenticated caller
• 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
• _offset to skip a number of matching samples before returning results

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.

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 or $hnz-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 resource used for SDHR data access verification workflows.

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. A patient's participation preferences should be managed by the Participate Operation. For more details on the participate operation see SDHR Custom Operations.

DRAFT PROFILE: Immunization resource for Shared Digital Health Record. This profile constrains Immunization to the SDHR subset of AIR immunization content. AIR reference: https://healthnz-prm.gitlab.io/air/air-api-fhir-ig/StructureDefinition-air-immunization.html

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.

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.

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.

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

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.

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 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.

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.

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.

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

DRAFT EXAMPLE ONLY: sampled AuditEvent returned for verification.

DRAFT EXAMPLE ONLY: sampled AuditEvent returned for verification.

DRAFT EXAMPLE ONLY: first page Bundle returned from the verification samples operation using _count and _offset.

DRAFT EXAMPLE ONLY: second page Bundle returned from the verification samples operation using _count and _offset.

DRAFT EXAMPLE ONLY: Bundle returned from the verification samples operation.

Example Hypertension Condition

Example Respiratory Condition

Consent example submitted to allow a patient to opt in to sharing their information, originating from a practice management system

Consent example to allow a patient to opt in to sharing their information, while withholding some records from the service

Consent example submitted to allow a patient to opt out of sharing their information. This example shows a Consent resource created as the result of an HNZ opt out.

Consent example submitted to allow a patient to opt out of sharing their information. This example shows a Consent resource created as the result of an HNZ opt out.

Consent example illustrating a patient stating participation preferences forsharing their information with SDHR at multiple facilities.

An example SDHR Vital Signs Observation

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 request where the patient has opted out of participating in the shared digital health record service.

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

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.

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.

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 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 when enrolment details are found for a patient who is not currently participating.

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

DRAFT EXAMPLE ONLY: Parameters payload posted to the verification submissions operation.

DRAFT EXAMPLE ONLY: 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.