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

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. The operation will return an OperationOutcome resource indicating the result of the operation.

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. The operation will return an OperationOutcome resource indicating the result of the operation.

AllergyIntolerance FHIR resource for Shared Digital Health Record

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.

Encounter resource to record an instance of an interaction between patient and healthcare provider

A Shared Digital Health Record Observation.

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

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.

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 Encounter Class system.

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

A ValueSet containing all codes from the SDHR Resource Tags 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

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

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.

Example Encounter resource to record an instance of an interaction between patient and healthcare provider

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.

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.

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