NZ Shared Digital Health Record API
1.0.0 - 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.0.0 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

## FHIR Artifacts

This page provides a list of the FHIR artifacts defined as part of this implementation guide.

### Behavior: Capability Statements

The following artifacts define the specific capabilities that different types of systems are expected to have in order to comply with this implementation guide. Systems conforming to this implementation guide are expected to declare conformance to one or more of the following capability statements.

NZ Shared Digital Health Record API | NZ Shared Digital Health Record API Capability Statement

### Behavior: Operation Definitions

These are custom operations that can be supported by and/or invoked by systems conforming to this implementation guide.

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

### Behavior: Search Parameters

These define the properties by which a RESTful server can be searched. They can also be used for sorting and including related resources.

condition-highlighted | Search for conditions flagged as highlighted in the SDHRCondition profile
condition-long-term-condition | Search for conditions marked as long term in the SDHRCondition profile

### Structures: Resource Profiles

These define constraints on FHIR resources for systems conforming to this implementation guide.

Batch Bundle with a Single Patient | 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.
SDHRAllergyIntolerance | AllergyIntolerance FHIR resource for Shared Digital Health Record
SDHRCondition | Condition resource to record problems and conditions affecting a person
SDHRConsent | 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.
SDHRObservation | A Shared Digital Health Record Observation.

### Structures: Extension Definitions

These define constraints on FHIR data types for systems conforming to this implementation guide.

Client Last Updated | 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
Facility Participation | 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.
HNZ SDHR Highlighted | 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.

### Terminology: Value Sets

These define sets of codes used by systems conforming to this implementation guide.

ValueSet for AllergyIntolerance Code | A ValueSet containing all codes from the AllergyIntolerance Code system.
ValueSet for AllergyIntolerance Manifestation | A ValueSet containing all codes from the AllergyIntolerance Manifestation system.
ValueSet for AllergyIntolerance Severity | A ValueSet containing all codes from the AllergyIntolerance Severity system.
ValueSet for SDHR Participation Reason | A ValueSet containing all codes from the SDHR Participation Reason system.
ValueSet for SDHR Resource Tags | A ValueSet containing all codes from the SDHR Resource Tags system.

### Terminology: Code Systems

These define new code systems used by systems conforming to this implementation guide.

NZ-specific terminology for Shared Digital Health Records | This system defines standard codes used throughout this Implementation Guide for New Zealand Shared Digital Health Records
SDHR Codes where the appropriate code is not known or can not be determined. | This code system is used when the appropriate code is not known or can not be determined.
SDHR Participation Reason Codes | This code system defines the reasons for a patient to participate in the Shared Digital Health Record service.
SDHR Specific Outcome Codes | This code system defines standard OperationOucome codes used throughout this Implementation Guide for New Zealand Shared Digital Health Records

### Example: Example Instances

These are example instances that show what data produced and consumed by systems conforming with this implementation guide might look like.

APIError-Confidential | Example OperationOutcome API response, returned when a resource has been flagged as confidential, and so cannot be accessed.
APIError-Unauthorised | 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.
AllergyIntoleranceExample | An example payload for a Primary Care AllergyIntolerance resource indicating an allergy to Penicillin, with a confidentiality of restricted.
AllergyIntoleranceExample2 | An example payload for a Primary Care AllergyIntolerance resource indicating an allergy to Cashew nuts
Batch-example |
ConditionHypertensionExample | Example Hypertension Condition
ConditionRespiratoryExample | Example Respiratory Condition
ConsentExample | Consent example submitted to allow a patient to opt in to sharing their information, originating from a practice management system
ConsentExampleRecordsWithheld | Consent example to allow a patient to opt in to sharing their information, while withholding some records from the service
ConsentFacilityDenyExample | 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.
ConsentHNZDenyExample | 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.
ConsentMultiFacilityExample | Consent example illustrating a patient stating participation preferences forsharing their information with SDHR at multiple facilities.
ObservationVitalSignsExample | An example SDHR Vital Signs Observation
OperationOutcomeFacilityDenyExample | Example OperationOutcome for a request where the patient has opted out of participating in the shared digital health record service for a specific facility.
OperationOutcomeFacilityLocked | 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.
OperationOutcomeFacilityUnknown | This outcome message will be returned where a facility is not yet onboarded to SDHR.
OperationOutcomeGlobalDenyExample | Example OperationOutcome for a request where the patient has opted out of participating in the shared digital health record service.
OperationOutcomeParticipateInvalidPatient | Example OperationOutcome for an invalid patient participation operation indicating that the patient parameter is invalid.
OperationOutcomeParticipateMissingReason | Example OperationOutcome for a missing reason code in the Participate operation indicating that the reason for participation status is required.
OperationOutcomeParticipatePreferencesNotKnown | Example OperationOutcome where a patient has not indicated their participation preferences for the Shared Digital Health Record service.
OperationOutcomeParticipateSuccess | Example OperationOutcome for a successful participation operation indicating that the patient's participation status was successfully recorded.
OperationOutcomePatientLocked | 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.
OperationOutcomeRateLimitExceeded | This outcome message will be returned where an API Consumer has exceeded the allocated rate limit.
OperationOutcomeRecordsWithheldAtSource | Example OperationOutcome when a patient has withheld records at source.
ParametersDoNotParticipate | Example parameters content to POST to the Participate operation where a patient does not wish to participate in the Shared Digital Health Record service.
ParametersHNZParticipateOptIn | 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.
ParametersHNZParticipateOptOut | 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.
ParametersParticipate | Example parameters content to POST to the Participate operation where a patient wishes to participate in the Shared Digital Health Record service.
ParametersParticipateRecordReleased | Example parameters content to POST to the Participate operation where a patient has individual records that are no longer withheld.
ParametersParticipateRecordWithheld | Example parameters content to POST to the Participate operation where a patient has individual records that are withheld - e.g. records marked as `Confidential`.
SearchConditionResponseExample | 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&amp;code=http://snomed.info/sct%7C38341003`
SearchConfidentialRecordsResponseExample | 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.
SearchExactMatchRecordWithheldExample | 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.
SearchWithRecordsWithheldExample | 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.