NZ Shared Digital Health Record API
1.1.6 - release
NZ Shared Digital Health Record API
1.1.6 - 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.1.6 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
| Active as of 2026-10-20 |
{
"resourceType" : "OperationDefinition",
"id" : "SDHRHNZParticipateOperation",
"text" : {
"status" : "generated",
"div" : "<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>\n</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)\nIf false, the patient does not wish to participate in the service and their resources will not be shared.</p>\n</div></td></tr><tr><td>IN</td><td>hnzOptOutReasonCode</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#code\">code</a></td><td><a href=\"ValueSet-sdhr-hnz-opt-out-reason-valueset.html\">ValueSet for HNZ Global Opt Out Reason</a> (Required)</td><td><div><p>Required when hnzParticipationIndicator is false. Not supported when hnzParticipationIndicator is true.\nAllowed values:</p>\n<ul>\n<li><code>patient-choice</code></li>\n<li><code>patient-deceased</code></li>\n<li><code>imported-external-consent</code></li>\n</ul>\n</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. Records are sourced only when the patient is already opted in at this facility; otherwise global opt-in succeeds without a load. A historic load is scheduled only for Pull based acquisition. This operation never changes facility participation. Not supported for global opt-out.</p>\n</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. Supply the configured PMS identifier used to select the historic load method. Not supported for global opt-out.</p>\n</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.\nThis parameter will contain an OperationOutcome resource indicating the success or failure of the operation.\nIf the operation is successful, the OperationOutcome will contain a success message.\nIf the operation fails, the OperationOutcome will contain an error message indicating the reason for the failure.\nThe OperationOutcome resource will be returned in the response body of the operation request.\nSee the following examples for possible OperationOutcome responses:\n- <a href=\"./OperationOutcome-OperationOutcomeParticipateInvalidPatient.html\">OperationOutcome for invalid patient reference</a>\n- <a href=\"./OperationOutcome-OperationOutcomeParticipateSuccess.html\">OperationOutcome for successful participation</a></p>\n</div></td></tr></table></div>"
},
"url" : "https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRHNZParticipateOperation",
"version" : "1.1.6",
"name" : "HNZParticipate",
"status" : "active",
"kind" : "operation",
"date" : "2026-10-20T03:14:47+00:00",
"publisher" : "Health New Zealand",
"contact" : [
{
"name" : "Health New Zealand",
"telecom" : [
{
"system" : "url",
"value" : "https://github.com/tewhatuora"
}
]
},
{
"name" : "HNZ Integration Team",
"telecom" : [
{
"system" : "email",
"value" : "integration@tewhatuora.govt.nz",
"use" : "work"
}
]
}
],
"description" : "This operation allows a patient to choose to participate in the Shared Digital Health Record service via HNZ assisted channels.\nThis operation should only be used by HNZ channels.\n\nScenarios where this operation might be used include:\n- A patient has opted in to the Shared Digital Health Record service by contacting Health NZ via appropriate digital or assisted channels.\n- 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.\n- 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.\n\nFor example payloads that might be used with this operation see:\n- [Parameters resource for total non-participation (patient choice)](./Parameters-ParametersHNZParticipateOptOut.html) : This example shows a global opt-out using reason `patient-choice`.\n- [Parameters resource for total non-participation (patient deceased)](./Parameters-ParametersHNZParticipateOptOutDeceased.html) : This example shows a global opt-out using reason `patient-deceased`.\n- [Parameters resource for total non-participation (imported external consent)](./Parameters-ParametersHNZParticipateOptOutImportedExternalConsent.html) : This example shows a global opt-out using reason `imported-external-consent`.\n- [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.\n- [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.\n\nTo 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`).\n\nThe operation is idempotent, meaning that multiple requests with the same parameters will have the same effect as a single request.\nThe 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.\nWhen `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.\nWhen 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](./OperationOutcome-OperationOutcomeGlobalDenyDeceasedExample.html): \"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](./api.html#global-participation-denial-api-behaviour).\nFor 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.\nWhen 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](./OperationOutcome-OperationOutcomeParticipateLoadScheduled.html).\nThe operation will return an OperationOutcome resource indicating the result of the operation.",
"code" : "hnz-participate",
"system" : true,
"type" : false,
"instance" : false,
"parameter" : [
{
"name" : "patient",
"use" : "in",
"min" : 1,
"max" : "*",
"documentation" : "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" : "Reference"
},
{
"name" : "hnzParticipationIndicator",
"use" : "in",
"min" : 1,
"max" : "1",
"documentation" : "Indicates global participation in the Shared Digital Health Record service (true/false)\nIf false, the patient does not wish to participate in the service and their resources will not be shared.",
"type" : "boolean"
},
{
"name" : "hnzOptOutReasonCode",
"use" : "in",
"min" : 0,
"max" : "1",
"documentation" : "Required when hnzParticipationIndicator is false. Not supported when hnzParticipationIndicator is true.\nAllowed values:\n- `patient-choice`\n- `patient-deceased`\n- `imported-external-consent`",
"type" : "code",
"binding" : {
"strength" : "required",
"valueSet" : "https://fhir-ig.digital.health.nz/sdhr/ValueSet/sdhr-hnz-opt-out-reason-valueset"
}
},
{
"name" : "facilityId",
"use" : "in",
"min" : 0,
"max" : "1",
"documentation" : "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. Records are sourced only when the patient is already opted in at this facility; otherwise global opt-in succeeds without a load. A historic load is scheduled only for Pull based acquisition. This operation never changes facility participation. Not supported for global opt-out.",
"type" : "Reference"
},
{
"name" : "pmsIdentifier",
"use" : "in",
"min" : 0,
"max" : "1",
"documentation" : "Required when facilityId is provided, otherwise omitted. Supply the configured PMS identifier used to select the historic load method. Not supported for global opt-out.",
"type" : "string"
},
{
"name" : "return",
"use" : "out",
"min" : 1,
"max" : "1",
"documentation" : "The result of the operation.\n This parameter will contain an OperationOutcome resource indicating the success or failure of the operation.\n If the operation is successful, the OperationOutcome will contain a success message.\n If the operation fails, the OperationOutcome will contain an error message indicating the reason for the failure.\n The OperationOutcome resource will be returned in the response body of the operation request.\n See the following examples for possible OperationOutcome responses:\n - [OperationOutcome for invalid patient reference](./OperationOutcome-OperationOutcomeParticipateInvalidPatient.html)\n - [OperationOutcome for successful participation](./OperationOutcome-OperationOutcomeParticipateSuccess.html)",
"type" : "OperationOutcome"
}
]
}