NZ Shared Digital Health Record API
1.0.2 - release
NZ Shared Digital Health Record API
1.0.2 - release
NZ Shared Digital Health Record API - Local Development build (v1.0.2) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| Active as of 2026-06-30 |
<OperationDefinition xmlns="http://hl7.org/fhir">
<id value="SDHRHNZParticipateOperation"/>
<text>
<status value="generated"/>
<div xmlns="http://www.w3.org/1999/xhtml"><p class="res-header-id"><b>Generated Narrative: OperationDefinition SDHRHNZParticipateOperation</b></p><a name="SDHRHNZParticipateOperation"> </a><a name="hcSDHRHNZParticipateOperation"> </a><p>URL: [base]/$hnz-participate</p><h3>Parameters</h3><table class="grid"><tr><td><b>Use</b></td><td><b>Name</b></td><td><b>Scope</b></td><td><b>Cardinality</b></td><td><b>Type</b></td><td><b>Binding</b></td><td><b>Documentation</b></td></tr><tr><td>IN</td><td>patient</td><td/><td>1..*</td><td><a href="http://hl7.org/fhir/R4/references.html#Reference">Reference</a></td><td/><td><div><p>Reference must be an NHI Patient URL with format https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZZZ1111 or ZZZ11AA. For global opt-in, repeat this parameter to opt in the complete linked NHI group. For global opt-out, exactly one patient parameter is supported.</p>
</div></td></tr><tr><td>IN</td><td>hnzParticipationIndicator</td><td/><td>1..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#boolean">boolean</a></td><td/><td><div><p>Indicates global participation in the Shared Digital Health Record service (true/false)
If false, the patient does not wish to participate in the service and their resources will not be shared.</p>
</div></td></tr><tr><td>IN</td><td>facilityId</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/references.html#Reference">Reference</a></td><td/><td><div><p>Optional for global opt-in. Reference must be an HPI Location URL for the enrolled provider, with format https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ999-B. If provided, pmsIdentifier is required. Not supported for global opt-out.</p>
</div></td></tr><tr><td>IN</td><td>pmsIdentifier</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#string">string</a></td><td/><td><div><p>Required when facilityId is provided, otherwise omitted. Must identify the PMS historic load method. Supported values are Medtech, Indici, and MyPractice. Not supported for global opt-out.</p>
</div></td></tr><tr><td>OUT</td><td>return</td><td/><td>1..1</td><td><a href="http://hl7.org/fhir/R4/operationoutcome.html">OperationOutcome</a></td><td/><td><div><p>The result of the operation.
This parameter will contain an OperationOutcome resource indicating the success or failure of the operation.
If the operation is successful, the OperationOutcome will contain a success message.
If the operation fails, the OperationOutcome will contain an error message indicating the reason for the failure.
The OperationOutcome resource will be returned in the response body of the operation request.
See the following examples for possible OperationOutcome responses:
- <a href="./OperationOutcome-OperationOutcomeParticipateInvalidPatient.html">OperationOutcome for invalid patient reference</a>
- <a href="./OperationOutcome-OperationOutcomeParticipateSuccess.html">OperationOutcome for successful participation</a></p>
</div></td></tr></table></div>
</text>
<url
value="https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRHNZParticipateOperation"/>
<version value="1.0.2"/>
<name value="HNZParticipate"/>
<status value="active"/>
<kind value="operation"/>
<date value="2026-06-30T04:46:48+00:00"/>
<publisher value="Health New Zealand"/>
<contact>
<name value="Health New Zealand"/>
<telecom>
<system value="url"/>
<value value="https://github.com/tewhatuora"/>
</telecom>
</contact>
<contact>
<name value="HNZ Integration Team"/>
<telecom>
<system value="email"/>
<value value="integration@tewhatuora.govt.nz"/>
<use value="work"/>
</telecom>
</contact>
<description
value="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](./Parameters-ParametersHNZParticipateOptOut.html) : 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](./Parameters-ParametersHNZParticipateOptIn.html) : 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](./Parameters-ParametersHNZParticipateLinkedGroupOptIn.html) : 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."/>
<code value="hnz-participate"/>
<system value="true"/>
<type value="false"/>
<instance value="false"/>
<parameter>
<name value="patient"/>
<use value="in"/>
<min value="1"/>
<max value="*"/>
<documentation
value="Reference must be an NHI Patient URL with format https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZZZ1111 or ZZZ11AA. For global opt-in, repeat this parameter to opt in the complete linked NHI group. For global opt-out, exactly one patient parameter is supported."/>
<type value="Reference"/>
</parameter>
<parameter>
<name value="hnzParticipationIndicator"/>
<use value="in"/>
<min value="1"/>
<max value="1"/>
<documentation
value="Indicates global participation in the Shared Digital Health Record service (true/false)
If false, the patient does not wish to participate in the service and their resources will not be shared."/>
<type value="boolean"/>
</parameter>
<parameter>
<name value="facilityId"/>
<use value="in"/>
<min value="0"/>
<max value="1"/>
<documentation
value="Optional for global opt-in. Reference must be an HPI Location URL for the enrolled provider, with format https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ999-B. If provided, pmsIdentifier is required. Not supported for global opt-out."/>
<type value="Reference"/>
</parameter>
<parameter>
<name value="pmsIdentifier"/>
<use value="in"/>
<min value="0"/>
<max value="1"/>
<documentation
value="Required when facilityId is provided, otherwise omitted. Must identify the PMS historic load method. Supported values are Medtech, Indici, and MyPractice. Not supported for global opt-out."/>
<type value="string"/>
</parameter>
<parameter>
<name value="return"/>
<use value="out"/>
<min value="1"/>
<max value="1"/>
<documentation
value="The result of the operation.
This parameter will contain an OperationOutcome resource indicating the success or failure of the operation.
If the operation is successful, the OperationOutcome will contain a success message.
If the operation fails, the OperationOutcome will contain an error message indicating the reason for the failure.
The OperationOutcome resource will be returned in the response body of the operation request.
See the following examples for possible OperationOutcome responses:
- [OperationOutcome for invalid patient reference](./OperationOutcome-OperationOutcomeParticipateInvalidPatient.html)
- [OperationOutcome for successful participation](./OperationOutcome-OperationOutcomeParticipateSuccess.html)"/>
<type value="OperationOutcome"/>
</parameter>
</OperationDefinition>