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
| Draft as of 2024-04-15 |
<CapabilityStatement xmlns="http://hl7.org/fhir">
<id value="SDHRCapabilityStatement"/>
<meta>
<profile
value="https://fhir-ig.digital.health.nz/hnz-digital-tooling/StructureDefinition/hnz-capability-statement"/>
</meta>
<text>
<status value="extensions"/>
<div xmlns="http://www.w3.org/1999/xhtml"><p class="res-header-id"><b>Generated Narrative: CapabilityStatement SDHRCapabilityStatement</b></p><a name="SDHRCapabilityStatement"> </a><a name="hcSDHRCapabilityStatement"> </a><div style="display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%"><p style="margin-bottom: 0px"/><p style="margin-bottom: 0px">Profile: <a href="file:///home/runner/work/fhir-ig-builder/fhir-ig-builder/hnz-digital-tooling/output/StructureDefinition-hnz-capability-statement.html">Capability Statement profile for use with the Health New Zealand Te Whatu Ora OpenAPI spec converter</a></p></div><h2 id="title">NZ Shared Digital Health Record API</h2><ul><li>Implementation Guide Version: 1.1.6 </li><li>FHIR Version: 4.0.1 </li><li>Supported Formats: <code>application/fhir+json</code></li><li>Published on: 2024-04-15 01:15:23+0000 </li><li>Published by: Health New Zealand </li></ul><blockquote class="impl-note"><p><strong>Note to Implementers: FHIR Capabilities</strong></p><p>Any FHIR capability may be 'allowed' by the system unless explicitly marked as 'SHALL NOT'. A few items are marked as MAY in the Implementation Guide to highlight their potential relevance to the use case.</p></blockquote><h2 id="rest">FHIR RESTful Capabilities</h2><div class="panel panel-default"><div class="panel-heading"><h3 id="mode1" class="panel-title">Mode: <code>server</code></h3></div><div class="panel-body"><div><h3>Request-Context custom header</h3>
<p>All FHIR API requests MUST include the HNZ request context <em>custom header</em> which supplies identifiers for the health user
and organisation, or system behind the API request.</p>
<p>This context is supplied using the 'Request-Context' custom HTTP header in the form of a base64-encoded JSON object.
The value of the header has differing forms based on the type of request being made, namely whether it is in a user context (e.g. a clinical user searching for patient records), or a system context (e.g. a system submitting data to the API in a bulk load scenario).</p>
<h4>Requests with user context</h4>
<table class="grid">
<thead>
<tr>
<th align="left"><strong>Context property</strong></th>
<th align="left"><strong>Mandatory</strong></th>
<th align="left"><strong>Value</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>userIdentifier</code></td>
<td align="left">Yes</td>
<td align="left">The userid of the user as authenticated by the PMS/health application</td>
</tr>
<tr>
<td align="left"><code>secondaryIdentifier</code></td>
<td align="left">Yes</td>
<td align="left">The secondary identifier for the user. Must be a JSON object with: <code>use</code> (one of <code>usual</code>, <code>official</code>, <code>temp</code>, <code>secondary</code>, <code>old</code>), <code>system</code> (must be <code>https://standards.digital.health.nz/ns/hpi-person-id</code>), and a non-empty <code>value</code></td>
</tr>
<tr>
<td align="left"><code>purposeOfUse</code></td>
<td align="left">Yes</td>
<td align="left">Exactly one of <code>[ "TREAT", "ETREAT" ]</code>. For descriptions of the values, see <a href="https://fhir-ig.digital.health.nz/auditevents/ValueSet-purposeofuse.html">Audit Events</a></td>
</tr>
<tr>
<td align="left"><code>userFullName</code></td>
<td align="left">Yes</td>
<td align="left">Full name of the user of the PMS/health application.</td>
</tr>
<tr>
<td align="left"><code>userRole</code></td>
<td align="left">Yes</td>
<td align="left">Role of the user of the PMS/health application. Set to <code>"PROV"</code> (Provider)</td>
</tr>
<tr>
<td align="left"><code>orgIdentifier</code></td>
<td align="left">Yes</td>
<td align="left">The HPI Organisation Number for the organisation in which the API consumer application is deployed. Must match the format <code>G[A-Z0-9]{5}-[A-Z]</code> (e.g. <code>G00001-G</code>)</td>
</tr>
<tr>
<td align="left"><code>facilityIdentifier</code></td>
<td align="left">Yes</td>
<td align="left">The HPI Facility identifier for the facility where the record is being sourced / accessed. Must match the format <code>F[A-Z0-9]{5}-[A-Z]</code> (e.g. <code>FZZ999-B</code>)</td>
</tr>
</tbody>
</table>
<h4>Requests with system context</h4>
<table class="grid">
<thead>
<tr>
<th align="left"><strong>Context property</strong></th>
<th align="left"><strong>Mandatory</strong></th>
<th align="left"><strong>Value</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><code>userIdentifier</code></td>
<td align="left">Yes</td>
<td align="left">The oAuth clientId of the system submitting data to the API</td>
</tr>
<tr>
<td align="left"><code>secondaryIdentifier</code></td>
<td align="left">No (forbidden)</td>
<td align="left">Must not be included in system-context requests</td>
</tr>
<tr>
<td align="left"><code>purposeOfUse</code></td>
<td align="left">Yes</td>
<td align="left">Must be exactly <code>[ "RECORDMGT" ]</code>. For descriptions of the values, see <a href="https://fhir-ig.digital.health.nz/auditevents/ValueSet-purposeofuse.html">Audit Events</a></td>
</tr>
<tr>
<td align="left"><code>userFullName</code></td>
<td align="left">Yes</td>
<td align="left">Name of the PMS/health application.</td>
</tr>
<tr>
<td align="left"><code>userRole</code></td>
<td align="left">Yes</td>
<td align="left">Role of the PMS/health application. Set to <code>"110150"</code> (Application)</td>
</tr>
<tr>
<td align="left"><code>orgIdentifier</code></td>
<td align="left">Yes</td>
<td align="left">The HPI Organisation Number for the organisation in which the API consumer application is deployed. Must match the format <code>G[A-Z0-9]{5}-[A-Z]</code> (e.g. <code>G00001-G</code>)</td>
</tr>
<tr>
<td align="left"><code>facilityIdentifier</code></td>
<td align="left">Yes</td>
<td align="left">The HPI Facility identifier for the facility. Must match the format <code>F[A-Z0-9]{5}-[A-Z]</code> (e.g. <code>FZZ999-B</code>)</td>
</tr>
</tbody>
</table>
<p>A schema definition and examples for <code>Request-Context</code> can be <a href="https://github.com/tewhatuora/schemas/blob/main/json-schema/Request-Context.json">found here</a></p>
<h4>Example Request-Context Header Payload for a clinical user searching for a patient's Conditions</h4>
<p><strong>Base64 Encoded</strong></p>
<pre><code>ewogICJ1c2VySWRlbnRpZmllciI6ICJwbXMtaWQtMTIzIiwKICAidXNlclJvbGUiOiAiUFJPViIsCiAgInNlY29uZGFyeUlkZW50aWZpZXIiOiB7CiAgICAidXNlIjogIm9mZmljaWFsIiwKICAgICJzeXN0ZW0iOiAiaHR0cHM6Ly9zdGFuZGFyZHMuZGlnaXRhbC5oZWFsdGgubnovbnMvaHBpLXBlcnNvbi1pZCIsCiAgICAidmFsdWUiOiAiOTlaWlpTIgogIH0sCiAgInB1cnBvc2VPZlVzZSI6IFsKICAgICJUUkVBVCIKICBdLAogICJ1c2VyRnVsbE5hbWUiOiAiQmV2ZXJseSBDcnVzaGVyIiwKICAib3JnSWRlbnRpZmllciI6ICJHMDAwMDEtRyIsCiAgImZhY2lsaXR5SWRlbnRpZmllciI6ICJGWlo5OTktQiIKfQ==
</code></pre>
<p><strong>Decoded JSON</strong></p>
<pre><code class="language-json">{
"userIdentifier": "pms-id-123",
"userRole": "PROV",
"secondaryIdentifier": {
"use": "official",
"system": "https://standards.digital.health.nz/ns/hpi-person-id",
"value": "99ZZZS"
},
"purposeOfUse": [
"TREAT"
],
"userFullName": "Beverly Crusher",
"orgIdentifier": "G00001-G",
"facilityIdentifier": "FZZ999-B"
}
</code></pre>
<h4>Example Request-Context Header Payload for a system submitting data to the API, where there is no end user</h4>
<p><strong>Base64 Encoded</strong></p>
<pre><code>ewogICAgInVzZXJJZGVudGlmaWVyIjogIjFiODIwMGQ3LTNhOGMtNGZiNi04ZTVjLWNlYzQ1NDA5OTlkNSIsCiAgICAidXNlclJvbGUiOiAiMTEwMTUwIiwKICAgICJwdXJwb3NlT2ZVc2UiOiBbCiAgICAgICAgIlJFQ09SRE1HVCIKICAgIF0sCiAgICAidXNlckZ1bGxOYW1lIjogIlNhbXBsZSBQTVMgSW50ZWdyYXRpb24gQXBwbGljYXRpb24iLAogICAgIm9yZ0lkZW50aWZpZXIiOiAiRzAwMDAxLUciLAogICAgImZhY2lsaXR5SWRlbnRpZmllciI6ICJGWlo5OTktQiIKfQ==
</code></pre>
<p><strong>Decoded JSON</strong></p>
<pre><code class="language-json">{
"userIdentifier": "1b8200d7-3a8c-4fb6-8e5c-cec4540999d5",
"userRole": "110150",
"purposeOfUse": [
"RECORDMGT"
],
"userFullName": "Sample PMS Integration Application",
"orgIdentifier": "G00001-G",
"facilityIdentifier": "FZZ999-B"
}
</code></pre>
<h3>Mandatory search parameters</h3>
<p>All FHIR API search requests must include the HNZ mandatory search parameters. These are listed in the Combined Search Parameters section of each resource below.</p>
<h3>Error status codes</h3>
<h4>Read (GET) Operation Statuses</h4>
<table class="grid">
<thead>
<tr>
<th align="center"><strong>Code</strong></th>
<th align="left"><strong>Meaning</strong></th>
<th align="left"><strong>Description</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td align="center">200</td>
<td align="left">OK</td>
<td align="left">The request was successful, and the response body contains the representation requested</td>
</tr>
<tr>
<td align="center">302</td>
<td align="left">FOUND</td>
<td align="left">A common redirect response; you can GET the representation at the URI in the Location response header</td>
</tr>
<tr>
<td align="center">304</td>
<td align="left">NOT MODIFIED</td>
<td align="left">Your client's cached version of the representation is still up to date</td>
</tr>
<tr>
<td align="center">400</td>
<td align="left">BAD REQUEST</td>
<td align="left">Missing or bad <code>Request-Context</code> custom header; FHIR request payload does not validate against Implementation Guide</td>
</tr>
<tr>
<td align="center">401</td>
<td align="left">UNAUTHORIZED</td>
<td align="left">The supplied credentials, if any, are not sufficient to access the resource</td>
</tr>
<tr>
<td align="center">403</td>
<td align="left">FORBIDDEN</td>
<td align="left">Insufficient privilege or participation denial. See <a href="./OperationOutcome-OperationOutcomeGlobalDenyExample.html">global denial</a> and <a href="./OperationOutcome-OperationOutcomeGlobalDenyDeceasedExample.html">global denial due to patient-deceased opt-out</a>.</td>
</tr>
<tr>
<td align="center">404</td>
<td align="left">NOT FOUND</td>
<td align="left">The requested representation was not found. Retrying this request is unlikely to be successful</td>
</tr>
<tr>
<td align="center">429</td>
<td align="left">TOO MANY REQUESTS</td>
<td align="left">Your application is sending too many simultaneous requests</td>
</tr>
<tr>
<td align="center">500</td>
<td align="left">SERVER ERROR</td>
<td align="left">An internal server error prevented return of the representation response</td>
</tr>
<tr>
<td align="center">503</td>
<td align="left">SERVICE UNAVAILABLE</td>
<td align="left">We are temporarily unable to return the representation. Please wait and try again later</td>
</tr>
</tbody>
</table>
<h4>Search (GET) Operation Statuses</h4>
<table class="grid">
<thead>
<tr>
<th align="center"><strong>Code</strong></th>
<th align="left"><strong>Meaning</strong></th>
<th align="left"><strong>OperationOutcome</strong> in response?</th>
<th align="left"><strong>Description</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td align="center">200</td>
<td align="left">OK</td>
<td align="left">Yes, When there are additional messages about a match result</td>
<td align="left">The request was successful, and the response body contains the representation requested</td>
</tr>
<tr>
<td align="center">302</td>
<td align="left">FOUND</td>
<td align="left">No</td>
<td align="left">A common redirect response; you can GET the representation at the URI in the Location response header</td>
</tr>
<tr>
<td align="center">400</td>
<td align="left">BAD REQUEST</td>
<td align="left">Yes</td>
<td align="left">Missing or bad <code>Request-Context</code> custom header;<br>FHIR request payload does not validate against Implementation Guide</td>
</tr>
<tr>
<td align="center">401</td>
<td align="left">UNAUTHORIZED</td>
<td align="left">Yes</td>
<td align="left">The supplied credentials, if any, are not sufficient to access the resource</td>
</tr>
<tr>
<td align="center">403</td>
<td align="left">FORBIDDEN</td>
<td align="left">Yes</td>
<td align="left">Insufficient privilege or participation denial. See <a href="./OperationOutcome-APIError-Unauthorised.html">OperationOutcome-APIError-Unauthorised</a>, <a href="./OperationOutcome-OperationOutcomeGlobalDenyExample.html">global denial</a>, and <a href="./OperationOutcome-OperationOutcomeGlobalDenyDeceasedExample.html">global denial due to patient-deceased opt-out</a>.</td>
</tr>
<tr>
<td align="center">429</td>
<td align="left">TOO MANY REQUESTS</td>
<td align="left">No</td>
<td align="left">Your application is sending too many simultaneous requests</td>
</tr>
<tr>
<td align="center">500</td>
<td align="left">SERVER ERROR</td>
<td align="left">No</td>
<td align="left">An internal server error prevented return of the representation response</td>
</tr>
<tr>
<td align="center">503</td>
<td align="left">SERVICE UNAVAILABLE</td>
<td align="left">No</td>
<td align="left">The server is temporarily unable to return the representation. Please wait and try again later</td>
</tr>
</tbody>
</table>
<h4>Update or Create (POST or PUT) Operation Statuses</h4>
<table class="grid">
<thead>
<tr>
<th align="center"><strong>Code</strong></th>
<th align="left"><strong>Meaning</strong></th>
<th align="left"><strong>OperationOutcome</strong> in response?</th>
<th align="left"><strong>Description</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td align="center">200</td>
<td align="left">OK</td>
<td align="left">Yes, When there are additional messages about an operation</td>
<td align="left">The request was successful, and the response body contains the representation requested</td>
</tr>
<tr>
<td align="center">201</td>
<td align="left">CREATED</td>
<td align="left">No</td>
<td align="left">The request was successful, and the response body contains the representation created</td>
</tr>
<tr>
<td align="center">400</td>
<td align="left">BAD REQUEST</td>
<td align="left">Yes</td>
<td align="left">Missing or bad <code>Request-Context</code> custom header;<br>FHIR request payload does not validate against Implementation Guide</td>
</tr>
<tr>
<td align="center">401</td>
<td align="left">UNAUTHORIZED</td>
<td align="left">Yes</td>
<td align="left">The supplied credentials, if any, are not sufficient to access the resource</td>
</tr>
<tr>
<td align="center">403</td>
<td align="left">FORBIDDEN</td>
<td align="left">Yes</td>
<td align="left">Insufficient privilege to access the requested FHIR resource/operation. See <a href="./OperationOutcome-APIError-Unauthorised.html">OperationOutcome-APIError-Unauthorised</a></td>
</tr>
<tr>
<td align="center">404</td>
<td align="left">NOT FOUND</td>
<td align="left">Yes</td>
<td align="left">The update target does not exist. Updating a missing resource does not create it</td>
</tr>
<tr>
<td align="center">409</td>
<td align="left">CONFLICT</td>
<td align="left">Yes</td>
<td align="left">A concurrent write or resource lock prevented the operation</td>
</tr>
<tr>
<td align="center">429</td>
<td align="left">TOO MANY REQUESTS</td>
<td align="left">Yes</td>
<td align="left">Your application is sending too many simultaneous requests</td>
</tr>
<tr>
<td align="center">500</td>
<td align="left">SERVER ERROR</td>
<td align="left">Yes</td>
<td align="left">An internal server error prevented return of the representation response</td>
</tr>
<tr>
<td align="center">503</td>
<td align="left">SERVICE UNAVAILABLE</td>
<td align="left">No</td>
<td align="left">The server is temporarily unable to return the representation. Please wait and try again later</td>
</tr>
</tbody>
</table>
<h3>Non existent API endpoints</h3>
<p>When a consumer attempts to call a non-existent API end point, respond
with a <strong>501 Not Implemented</strong> status code.</p>
<h3>API Rate Limits</h3>
<p>API rate limiting is enforced on a per client basis, and the status of the rate limit is communicated via the following HTTP response headers:</p>
<table class="grid">
<thead>
<tr>
<th align="left"><strong>Header name</strong></th>
<th align="left"><strong>Description</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">x-ratelimit-remaining</td>
<td align="left">The amount of available quota</td>
</tr>
<tr>
<td align="left">x-ratelimit-limit</td>
<td align="left">The maximum available requests per window</td>
</tr>
<tr>
<td align="left">x-ratelimit-reset</td>
<td align="left">The remaining time, in milliseconds, until a new window starts</td>
</tr>
</tbody>
</table>
<p>The API client <strong>MUST</strong> monitor these headers and ensure that they do not exceed the quota expressed in the <code>x-ratelimit-limit</code> header before the time window expressed in <code>x-ratelimit-reset</code>.
If the rate limit is exceeded, the API will respond with a <strong>429 Too Many Requests</strong> status code and the <a href="./OperationOutcome-OperationOutcomeRateLimitExceeded.json.html">Rate Limit OperationOutcome</a>.</p>
<table class="grid">
<thead>
<tr>
<th align="left"><strong>Usage plan</strong></th>
<th align="left"><strong>Rate limits</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">SDHR Gold</td>
<td align="left">400 requests per second, per client</td>
</tr>
<tr>
<td align="left">SDHR Silver</td>
<td align="left">50 requests per second, per client</td>
</tr>
<tr>
<td align="left">SDHR Bronze</td>
<td align="left">10 requests per second, per client</td>
</tr>
</tbody>
</table>
<p>Where the rate limit is exceeded as part of normal operations, the API client can request an increased quota by contacting the SDHR service desk portal.</p>
</div><div class="lead"><em>Security</em></div><div class="row"><div class="col-lg-6">Enable CORS: yes</div><div class="col-lg-6">Security services supported: <code>SMART-on-FHIR</code></div></div><blockquote><div><p>OAuth 2.0 - Client Credential flow.</p>
</div></blockquote><div class="lead"><em>Summary of System-wide Interactions</em></div><ul><li>Supports the <code>search-system</code>interaction.</li><li>Supports the <code>transaction</code>interaction.</li><li>Supports the <code>batch</code>interaction.</li></ul><div class="row"><div class="col-12"><span class="lead">Summary of System-wide Operations</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Operation</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="OperationDefinition-SDHRParticipateOperation.html">$participate</a></td><td><div><p>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.</p>
<p>Scenarios where this operation might be used include:</p>
<ul>
<li>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.</li>
<li>A patient chooses not to participate in the Shared Digital Health Record service and informs their healthcare provider of this choice.</li>
<li>A patient has one or more confidential records, held at their healthcare provider, that are withheld from the service.</li>
<li>A patient has previously withheld records but has now released them to the Shared Digital Health Record service.</li>
</ul>
<p>For example payloads that might be used with this operation see:</p>
<ul>
<li><a href="./Parameters-ParametersDoNotParticipate.html">Parameters resource for total non-participation</a> : This example shows how to indicate that a patient does not wish to participate in the Shared Digital Health Record service (has opted out).</li>
<li><a href="./Parameters-ParametersParticipate.html">Parameters resource for participation</a> : 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).</li>
<li><a href="./Parameters-ParametersParticipateRecordWithheld.html">Parameters resource for partial participation with withheld records</a> : This example shows how to indicate that a patient has some confidential records that are withheld from the Shared Digital Health Record service.</li>
<li><a href="./Parameters-ParametersParticipateRecordReleased.html">Parameters resource for releasing withheld records</a> : 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.</li>
</ul>
<p>To make a request to this operation the API Consumer must POST a <code>Parameters</code> payload to the operation URL (e.g. <code>POST https://api.sdhr.digital.health.nz/s2s/$participate</code>).</p>
<p>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.
When <code>participationIndicator</code> is <code>false</code>, SDHR records the facility opt-out and archives the patient's active contributed resources from the supplied facility. Archived resources are not returned by normal search or read interactions.
For an opt-in request using pull-based acquisition, the PMS may set <code>enrolledPatient</code> to <code>true</code> to indicate that the patient is enrolled at the supplied facility and that a historic load should be triggered. If <code>enrolledPatient</code> is omitted, the API updates consent without triggering a historic load.
When a historic load is scheduled, the returned OperationOutcome includes the informational <code>sdhr-historic-load-scheduled</code> issue. This confirms scheduling, not successful completion. The issue is absent when no load is scheduled, including an unchanged repeated request. See <a href="./OperationOutcome-OperationOutcomeParticipateLoadScheduled.html">historic-load scheduling outcome</a>.
The operation will return an OperationOutcome resource indicating the result of the operation.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="OperationDefinition-SDHRHNZParticipateOperation.html">$hnz-participate</a></td><td><div><p>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.</p>
<p>Scenarios where this operation might be used include:</p>
<ul>
<li>A patient has opted in to the Shared Digital Health Record service by contacting Health NZ via appropriate digital or assisted channels.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>For example payloads that might be used with this operation see:</p>
<ul>
<li><a href="./Parameters-ParametersHNZParticipateOptOut.html">Parameters resource for total non-participation (patient choice)</a> : This example shows a global opt-out using reason <code>patient-choice</code>.</li>
<li><a href="./Parameters-ParametersHNZParticipateOptOutDeceased.html">Parameters resource for total non-participation (patient deceased)</a> : This example shows a global opt-out using reason <code>patient-deceased</code>.</li>
<li><a href="./Parameters-ParametersHNZParticipateOptOutImportedExternalConsent.html">Parameters resource for total non-participation (imported external consent)</a> : This example shows a global opt-out using reason <code>imported-external-consent</code>.</li>
<li><a href="./Parameters-ParametersHNZParticipateOptIn.html">Parameters resource for participation</a> : This example shows how to indicate that a patient wishes to participate in the Shared Digital Health Record service.</li>
<li><a href="./Parameters-ParametersHNZParticipateLinkedGroupOptIn.html">Parameters resource for linked group participation</a> : This example shows how to indicate that all patients in a linked NHI group wish to participate in the Shared Digital Health Record service.</li>
</ul>
<p>To make a request to this operation the API Consumer must POST a <code>Parameters</code> payload to the operation URL (e.g. <code>POST https://api.sdhr.digital.health.nz/s2s/$hnz-participate</code>).</p>
<p>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 <code>patient</code> parameters may be supplied. Multiple <code>patient</code> 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 <code>patient</code> parameters are not supported for global opt-out requests.
When <code>hnzParticipationIndicator</code> is <code>false</code>, SDHR requires <code>hnzOptOutReasonCode</code>, records the global opt-out reason, and archives the patient's active contributed resources across all facilities. Archived resources are not returned by normal search or read interactions.
When the recorded reason is <code>patient-deceased</code>, subsequent resource read or search requests rejected by the global consent check return HTTP 403 with the <a href="./OperationOutcome-OperationOutcomeGlobalDenyDeceasedExample.html">deceased global-denial OperationOutcome</a>: "Patient data is unavailable in the Shared Digital Health Record as they are deceased." This is not the response to a successful <code>$hnz-participate</code> request; see <a href="./api.html#global-participation-denial-api-behaviour">global participation denial API behaviour</a>.
For a global opt-in request where the patient is enrolled with a provider, the request may include the enrolled provider <code>facilityId</code> and must then include <code>pmsIdentifier</code>. 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 <code>facilityId</code> is omitted, <code>pmsIdentifier</code> must also be omitted and no historic load is scheduled.
When a historic load is scheduled, the returned OperationOutcome includes the informational <code>sdhr-historic-load-scheduled</code> issue. This confirms scheduling, not successful completion. The issue is absent when no load is scheduled, including an unchanged repeated request. See <a href="./OperationOutcome-OperationOutcomeParticipateLoadScheduled.html">historic-load scheduling outcome</a>.
The operation will return an OperationOutcome resource indicating the result of the operation.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="OperationDefinition-SDHRHNZDomainParticipateOperation.html">$hnz-domain-participate</a></td><td><div><p>Records one or more domain choices on exactly one patient's Consent through authorised Health NZ channels. Supply one patient and one domains parameter with named boolean parts. Linked Consents are unchanged; any linked domain deny blocks access for the group. Global participation remains managed through $hnz-participate.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="OperationDefinition-SDHRHNZParticipationStatusOperation.html">$hnz-participation-status</a></td><td><div><p>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, the global opt-out reason when applicable, 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.</p>
<p>This operation requires the SMART on FHIR scope <code>https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRHNZParticipationStatusOperation</code>.</p>
<p>For an example response payload for this operation see:</p>
<ul>
<li><a href="./Parameters-ParametersParticipationStatusResponse.html">Parameters resource for participation status response</a> : This example shows the <code>Parameters</code> resource returned by the operation when participation status information is found for a patient.</li>
<li><a href="./Parameters-ParametersParticipationStatusEnrolmentResponse.html">Parameters resource for participation status response after opt-out</a> : This example shows an enrolled patient with archived records after opting out.</li>
</ul>
<p>To make a request to this operation the API Consumer must POST a <code>Parameters</code> payload to the operation URL (e.g. <code>POST https://api.sdhr.digital.health.nz/s2s/$hnz-participation-status</code>).</p>
<p>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 <code>Parameters</code> resource containing the patient reference and participation status indicators.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="OperationDefinition-SDHRParticipationStatusOperation.html">$participation-status</a></td><td><div><p>This operation allows Shared Electronic Health Record (SEHR) systems to retrieve a patient's Shared Digital Health Record participation status.</p>
<p>For an example response payload for this operation see:</p>
<ul>
<li><a href="./Parameters-ParametersParticipationStatusNotParticipatingResponse.html">Parameters resource for participation status response - not participating</a> : This example shows the <code>Parameters</code> resource returned when the patient is not participating in the Shared Digital Health Record service.</li>
<li><a href="./Parameters-ParametersParticipationStatusParticipatingResponse.html">Parameters resource for participation status response - participating</a> : This example shows the <code>Parameters</code> resource returned when the patient is participating in the Shared Digital Health Record service.</li>
</ul>
<p>To make a request to this operation the API Consumer must POST a <code>Parameters</code> payload to the operation URL (e.g. <code>POST https://api.sdhr.digital.health.nz/s2s/$participation-status</code>).</p>
<p>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.
This operation requires the SMART on FHIR scope <code>https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRParticipationStatusOperation</code>.
The operation returns a <code>Parameters</code> resource containing only <code>hnzParticipationIndicator</code>. A patient with no recorded global participation preference is considered to be participating and returns <code>true</code>.</p>
</div></td></tr></tbody></table></div></div></div></div><h3 id="resourcesCap1">Capabilities by Resource/Profile</h3><h4 id="resourcesSummary1">Summary</h4><p>The summary table lists the resources that are part of this configuration, and for each resource it lists:</p><ul><li>The relevant profiles (if any)</li><li>The interactions supported by each resource (<b><span class="bg-info">R</span></b>ead, <b><span class="bg-info">S</span></b>earch, <b><span class="bg-info">U</span></b>pdate, and <b><span class="bg-info">C</span></b>reate, are always shown, while <b><span class="bg-info">VR</span></b>ead, <b><span class="bg-info">P</span></b>atch, <b><span class="bg-info">D</span></b>elete, <b><span class="bg-info">H</span></b>istory on <b><span class="bg-info">I</span></b>nstance, or <b><span class="bg-info">H</span></b>istory on <b><span class="bg-info">T</span></b>ype are only present if at least one of the resources has support for them.</li><li><span>The required, recommended, and some optional search parameters (if any). </span></li><li>The linked resources enabled for <code>_include</code></li><li>The other resources enabled for <code>_revinclude</code></li><li>The operations on the resource (if any)</li></ul><div class="table-responsive"><table class="table table-condensed table-hover"><thead><tr><th><b>Resource Type</b></th><th><b>Profile</b></th><th class="text-center"><b title="GET a resource (read interaction)">R</b></th><th class="text-center"><b title="GET all set of resources of the type (search interaction)">S</b></th><th class="text-center"><b title="PUT a new resource version (update interaction)">U</b></th><th class="text-center"><b title="POST a new resource (create interaction)">C</b></th><th class="text-center"><b title="DELETE a resource (delete interaction)">D</b></th><th><b title="Required and recommended search parameters">Searches</b></th><th><code><b>_include</b></code></th><th><code><b>_revinclude</b></code></th><th><b>Operations</b></th></tr></thead><tbody><tr><td><a href="#AllergyIntolerance1-1">AllergyIntolerance</a></td><td><a href="StructureDefinition-SDHRAllergyIntolerance.html">https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAllergyIntolerance</a></td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center">y</td><td>patient, category, clinical-status, code, identifier, recorder, severity, clientlastupdated, _lastUpdated, patient</td><td/><td/><td/></tr><tr><td><a href="#Condition1-2">Condition</a></td><td><a href="StructureDefinition-SDHRCondition.html">https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRCondition</a></td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center">y</td><td>patient, category, code, encounter, identifier, onset-date, severity, subject, highlighted, long-term-condition, clientlastupdated, _lastUpdated, patient</td><td><code>Condition:encounter</code></td><td/><td/></tr><tr><td><a href="#AuditEvent1-3">AuditEvent</a></td><td><a href="StructureDefinition-SDHRAuditEvent.html">https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAuditEvent</a><br/><em>Additional supported profiles:</em><br/> <a href="StructureDefinition-SDHRAuditEvent.html">SDHRAuditEvent</a></td><td class="text-center"/><td class="text-center"/><td class="text-center"/><td class="text-center"/><td class="text-center"/><td/><td/><td/><td><code>$verification-samples</code>, <code>$verification-submissions</code></td></tr><tr><td><a href="#Observation1-4">Observation</a></td><td><a href="StructureDefinition-SDHRObservation.html">https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRObservation</a></td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center">y</td><td>patient, category, code, date, encounter, identifier, performer, status, subject, value-concept, value-date, value-quantity, value-string, clientlastupdated, _lastUpdated, patient</td><td/><td/><td/></tr><tr><td><a href="#Immunization1-5">Immunization</a></td><td><a href="StructureDefinition-SDHRImmunization.html">https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRImmunization</a></td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center"/><td class="text-center"/><td class="text-center"/><td>patient, date, location, vaccine-code, target-disease, status, status-reason, product, _sort, patient</td><td/><td/><td/></tr><tr><td><a href="#MedicationRequest1-6">MedicationRequest</a></td><td><a href="StructureDefinition-SDHRMedicationRequest.html">https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRMedicationRequest</a></td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center"/><td class="text-center"/><td class="text-center"/><td>patient, identifier, status, code, location, _count, ct, authoredon, _sort, _revinclude, patient</td><td/><td><code>MedicationDispense:prescription</code></td><td/></tr><tr><td><a href="#MedicationDispense1-7">MedicationDispense</a></td><td><a href="StructureDefinition-SDHRMedicationDispense.html">https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRMedicationDispense</a></td><td class="text-center">y</td><td class="text-center">y</td><td class="text-center"/><td class="text-center"/><td class="text-center"/><td>patient, identifier, status, code, location, _count, ct, whenprepared, whenhandedover, _sort, _include, patient</td><td><code>MedicationDispense:prescription</code></td><td/><td/></tr></tbody></table></div><hr/><div class="panel panel-default"><div class="panel-heading"><h4 id="AllergyIntolerance1-1" class="panel-title"><span style="float: right;">Resource Conformance: unspecified </span>AllergyIntolerance</h4></div><div class="panel-body"><div class="container"><div class="row"><div class="col-lg-6"><span class="lead">Base System Profile</span><br/><a href="StructureDefinition-SDHRAllergyIntolerance.html">SDHRAllergyIntolerance</a></div><div class="col-lg-3"><span class="lead">Profile Conformance</span><br/><b>SHALL</b></div><div class="col-lg-3"><span class="lead">Reference Policy</span><br/></div></div><p/><div class="row"><div class="col-lg-6"><span class="lead">Interaction summary</span><br/><ul><li>Supports <code>read</code>, <code>create</code>, <code>update</code>, <code>search-type</code>, <code>delete</code>.</li></ul></div></div><p/><div class="row"><div class="col-12"><span class="lead">Documentation</span><blockquote><div><p>Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role.</p>
</div></blockquote></div></div><div class="row"><div class="col-lg-7"><span class="lead">Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameter</th><th>Type</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/allergyintolerance.html#search">patient</a></td><td><code>reference</code></td><td><div><p>MANDATORY
Who the sensitivity is for
<a href="http://hl7.org/fhir/R4/patient.html">Patient</a></p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/allergyintolerance.html#search">category</a></td><td><code>token</code></td><td><div><p>Must be one of</p>
<ul>
<li>food</li>
<li>medication</li>
<li>environment</li>
<li>biologic
<a href="http://hl7.org/fhir/ValueSet/allergy-intolerance-category">AllergyIntolerance Category ValueSet</a></li>
</ul>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/allergyintolerance.html#search">clinical-status</a></td><td><code>token</code></td><td><div><p>Must be one of</p>
<ul>
<li>active</li>
<li>inactive</li>
<li>resolved
<a href="http://hl7.org/fhir/R4/valueset-allergyintolerance-clinical.html">AllergyIntolerance Clinical Status ValueSet</a></li>
</ul>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/allergyintolerance.html#search">code</a></td><td><code>token</code></td><td><div><p>Code that identifies the allergy or intolerance
<a href="http://hl7.org/fhir/ValueSet/allergyintolerance-code">AllergyIntolerance Code ValueSet</a></p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/allergyintolerance.html#search">identifier</a></td><td><code>token</code></td><td><div><p>A unique identifier assigned to this resource.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/allergyintolerance.html#search">recorder</a></td><td><code>reference</code></td><td><div><p>Who recorded the sensitivity
<a href="http://hl7.org/fhir/R4/allergyintolerance-definitions.html#AllergyIntolerance.recorder">AllergyIntolerance.recorder</a></p>
</div></td></tr><tr><td><b>SHALL</b></td><td>severity</td><td><code>token</code></td><td><div><p>mild | moderate | severe (of event as a whole).</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="SearchParameter-allergyintolerance-clientlastupdated.html">clientlastupdated</a></td><td><code>date</code></td><td><div><p>The ClientLastUpdated extension value. This date parameter can also be used with <code>_sort=clientlastupdated</code> or <code>_sort=-clientlastupdated</code>.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/resource.html#search">_lastUpdated</a></td><td><code>date</code></td><td><div><p>When the resource version last changed</p>
</div></td></tr></tbody></table></div><div class="col-lg-5"><span class="lead">Combined Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameters</th><th>Types</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/allergyintolerance.html#search">patient</a></td><td><code>reference</code></td></tr></tbody></table></div></div></div></div></div><div class="panel panel-default"><div class="panel-heading"><h4 id="Condition1-2" class="panel-title"><span style="float: right;">Resource Conformance: unspecified </span>Condition</h4></div><div class="panel-body"><div class="container"><div class="row"><div class="col-lg-6"><span class="lead">Base System Profile</span><br/><a href="StructureDefinition-SDHRCondition.html">SDHRCondition</a></div><div class="col-lg-3"><span class="lead">Profile Conformance</span><br/><b>SHALL</b></div><div class="col-lg-3"><span class="lead">Reference Policy</span><br/></div></div><p/><div class="row"><div class="col-lg-6"><span class="lead">Interaction summary</span><br/><ul><li>Supports <code>read</code>, <code>create</code>, <code>update</code>, <code>search-type</code>, <code>delete</code>.</li></ul></div></div><p/><div class="row"><div class="col-12"><span class="lead">Documentation</span><blockquote><div><p>Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role.</p>
</div></blockquote></div></div><div class="row"><div class="col-lg-7"><span class="lead">Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameter</th><th>Type</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/condition.html#search">patient</a></td><td><code>reference</code></td><td><div><p><strong>MANDATORY</strong>
Who has the condition?</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/condition.html#search">category</a></td><td><code>token</code></td><td><div><p>The category of the condition</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/condition.html#search">code</a></td><td><code>token</code></td><td><div><p>The code for the condition</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/condition.html#search">encounter</a></td><td><code>reference</code></td><td><div><p>Encounter associated with the condition</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/condition.html#search">identifier</a></td><td><code>token</code></td><td><div><p>A unique identifier assigned to this resource.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/condition.html#search">onset-date</a></td><td><code>date</code></td><td><div><p>Date the condition started</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/condition.html#search">severity</a></td><td><code>token</code></td><td><div><p>The severity of the condition</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/condition.html#search">subject</a></td><td><code>reference</code></td><td><div><p>Who has the condition?</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="SearchParameter-condition-highlighted.html">highlighted</a></td><td><code>token</code></td><td><div><p>Search for conditions flagged as highlighted in the SDHRCondition profile</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="SearchParameter-condition-long-term-condition.html">long-term-condition</a></td><td><code>token</code></td><td><div><p>Search for conditions flagged as long term in the SDHRCondition profile</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="SearchParameter-condition-clientlastupdated.html">clientlastupdated</a></td><td><code>date</code></td><td><div><p>The ClientLastUpdated extension value. This date parameter can also be used with <code>_sort=clientlastupdated</code> or <code>_sort=-clientlastupdated</code>.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/resource.html#search">_lastUpdated</a></td><td><code>date</code></td><td><div><p>When the resource version last changed.</p>
</div></td></tr></tbody></table></div><div class="col-lg-5"><span class="lead">Combined Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameters</th><th>Types</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/condition.html#search">patient</a></td><td><code>reference</code></td></tr></tbody></table></div></div></div></div></div><div class="panel panel-default"><div class="panel-heading"><h4 id="AuditEvent1-3" class="panel-title"><span style="float: right;">Resource Conformance: unspecified </span>AuditEvent</h4></div><div class="panel-body"><div class="container"><div class="row"><div class="col-lg-6"><span class="lead">Base System Profile</span><br/><a href="StructureDefinition-SDHRAuditEvent.html">SDHRAuditEvent</a></div><div class="col-lg-3"><span class="lead">Profile Conformance</span><br/><b>SHALL</b></div><div class="col-lg-3"><span class="lead">Reference Policy</span><br/></div></div><p/><div class="row"><div class="col-6"><span class="lead">Supported Profiles</span><p><a href="StructureDefinition-SDHRAuditEvent.html">SDHRAuditEvent</a></p></div><div class="col-lg-6"><span class="lead">Interaction summary</span><br/><ul/></div></div><p/><div class="row"><div class="col-12"><span class="lead">Documentation</span><blockquote><div><p>AuditEvent supports DRAFT custom operations for data viewer application verification workflows.</p>
</div></blockquote></div></div><div class="row"><div class="col-12"><span class="lead">Extended Operations</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Operation</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="OperationDefinition-SDHRVerificationSamplesOperation.html">$verification-samples</a></td><td><div><p>Returns sampled AuditEvent resources that are still outstanding for verification by the authenticated data viewer application. Successful requests return a searchset Bundle, which may be empty. Supports optional <code>_count</code> and <code>_getpagesoffset</code> query parameters for paging. Generic AuditEvent interactions are not supported.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="OperationDefinition-SDHRVerificationSubmissionsOperation.html">$verification-submissions</a></td><td><div><p>DRAFT OPERATION: Accepts a Parameters payload containing one or more verification decisions for sampled AuditEvent resources.</p>
</div></td></tr></tbody></table></div></div></div></div></div><div class="panel panel-default"><div class="panel-heading"><h4 id="Observation1-4" class="panel-title"><span style="float: right;">Resource Conformance: unspecified </span>Observation</h4></div><div class="panel-body"><div class="container"><div class="row"><div class="col-lg-6"><span class="lead">Base System Profile</span><br/><a href="StructureDefinition-SDHRObservation.html">SDHRObservation</a></div><div class="col-lg-3"><span class="lead">Profile Conformance</span><br/><b>SHALL</b></div><div class="col-lg-3"><span class="lead">Reference Policy</span><br/></div></div><p/><div class="row"><div class="col-lg-6"><span class="lead">Interaction summary</span><br/><ul><li>Supports <code>read</code>, <code>create</code>, <code>update</code>, <code>search-type</code>, <code>delete</code>.</li></ul></div></div><p/><div class="row"><div class="col-12"><span class="lead">Documentation</span><blockquote><div><p>Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role.</p>
</div></blockquote></div></div><div class="row"><div class="col-lg-7"><span class="lead">Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameter</th><th>Type</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">patient</a></td><td><code>reference</code></td><td><div><p><strong>MANDATORY</strong>
Who the observation is for
<a href="http://hl7.org/fhir/R4/patient.html">Patient</a></p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">category</a></td><td><code>token</code></td><td><div><p>The classification of the type of observation</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">code</a></td><td><code>token</code></td><td><div><p>Describes what was observed. Sometimes this is called the observation 'name'</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">date</a></td><td><code>date</code></td><td><div><p>Observation.effective
Obtained date/time. If the obtained element is a period, a date that falls in the period</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">encounter</a></td><td><code>reference</code></td><td><div><p>The Encounter resource associated with the Observation.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">identifier</a></td><td><code>token</code></td><td><div><p>A unique identifier assigned to this resource.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">performer</a></td><td><code>reference</code></td><td><div><p>Who performed the observation</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">status</a></td><td><code>token</code></td><td><div><p>The status of the observation</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">subject</a></td><td><code>reference</code></td><td><div><p>The subject that the observation is about</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">value-concept</a></td><td><code>token</code></td><td><div><p>The value of the observation, if the value is a CodeableConcept</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">value-date</a></td><td><code>date</code></td><td><div><p>The value of the observation, if the value is a date or period of time</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">value-quantity</a></td><td><code>quantity</code></td><td><div><p>The value of the observation, if the value is a Quantity, or a SampledData (just search on the bounds of the values in sampled data)</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">value-string</a></td><td><code>string</code></td><td><div><p>The value of the observation, if the value is a string, and also searches in CodeableConcept.text</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="SearchParameter-observation-clientlastupdated.html">clientlastupdated</a></td><td><code>date</code></td><td><div><p>The ClientLastUpdated extension value. This date parameter can also be used with <code>_sort=clientlastupdated</code> or <code>_sort=-clientlastupdated</code>.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/resource.html#search">_lastUpdated</a></td><td><code>date</code></td><td><div><p>When the resource version last changed.</p>
</div></td></tr></tbody></table></div><div class="col-lg-5"><span class="lead">Combined Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameters</th><th>Types</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/observation.html#search">patient</a></td><td><code>reference</code></td></tr></tbody></table></div></div></div></div></div><div class="panel panel-default"><div class="panel-heading"><h4 id="Immunization1-5" class="panel-title"><span style="float: right;">Resource Conformance: unspecified </span>Immunization</h4></div><div class="panel-body"><div class="container"><div class="row"><div class="col-lg-6"><span class="lead">Base System Profile</span><br/><a href="StructureDefinition-SDHRImmunization.html">SDHRImmunization</a></div><div class="col-lg-3"><span class="lead">Profile Conformance</span><br/><b>SHALL</b></div><div class="col-lg-3"><span class="lead">Reference Policy</span><br/></div></div><p/><div class="row"><div class="col-lg-6"><span class="lead">Interaction summary</span><br/><ul><li>Supports <code>read</code>, <code>search-type</code>.</li></ul></div></div><p/><div class="row"><div class="col-12"><span class="lead">Documentation</span><blockquote><div><p>Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role.</p>
</div></blockquote></div></div><div class="row"><div class="col-lg-7"><span class="lead">Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameter</th><th>Type</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/immunization.html#search">patient</a></td><td><code>reference</code></td><td><div><p><strong>MANDATORY</strong>
Who the immunization is for
<a href="http://hl7.org/fhir/R4/patient.html">Patient</a></p>
</div></td></tr><tr><td><b>SHALL</b></td><td>date</td><td><code>date</code></td><td><div><p>Vaccination (occurrence) date. Comparators eq, ge, gt, le, lt are supported; two <code>date</code> parameters may be combined for a range.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/immunization.html#search">location</a></td><td><code>reference</code></td><td><div><p>Facility (HPI) where the vaccination was administered.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/immunization.html#search">vaccine-code</a></td><td><code>token</code></td><td><div><p>Vaccine product administered. Supports <code>system|code</code> or bare <code>code</code>, and the <code>:text</code> modifier for name search.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/immunization.html#search">target-disease</a></td><td><code>token</code></td><td><div><p>Disease targeted by the vaccination (protocolApplied.targetDisease, SNOMED).</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/immunization.html#search">status</a></td><td><code>token</code></td><td><div><p>Immunisation event status. Records with status <code>entered-in-error</code> are excluded from search results.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/immunization.html#search">status-reason</a></td><td><code>token</code></td><td><div><p>Reason a vaccination was not administered.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>product</td><td><code>token</code></td><td><div><p>Administered product from the AIR administered-product extension, distinct from vaccine-code. Supports system|code or bare code, and :text for case-insensitive substring matching against text or coding display.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>_sort</td><td><code>string</code></td><td><div><p>Sort by occurrence date: date for ascending or -date for descending. Default: -date.</p>
</div></td></tr></tbody></table></div><div class="col-lg-5"><span class="lead">Combined Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameters</th><th>Types</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/immunization.html#search">patient</a></td><td><code>reference</code></td></tr></tbody></table></div></div></div></div></div><div class="panel panel-default"><div class="panel-heading"><h4 id="MedicationRequest1-6" class="panel-title"><span style="float: right;">Resource Conformance: unspecified </span>MedicationRequest</h4></div><div class="panel-body"><div class="container"><div class="row"><div class="col-lg-6"><span class="lead">Base System Profile</span><br/><a href="StructureDefinition-SDHRMedicationRequest.html">SDHRMedicationRequest</a></div><div class="col-lg-3"><span class="lead">Profile Conformance</span><br/><b>SHALL</b></div><div class="col-lg-3"><span class="lead">Reference Policy</span><br/></div></div><p/><div class="row"><div class="col-lg-6"><span class="lead">Interaction summary</span><br/><ul><li>Supports <code>read</code>, <code>search-type</code>.</li></ul></div></div><p/><div class="row"><div class="col-12"><span class="lead">Documentation</span><blockquote><div><p>Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role.</p>
</div></blockquote></div></div><div class="row"><div class="col-lg-7"><span class="lead">Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameter</th><th>Type</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/medicationrequest.html#search">patient</a></td><td><code>reference</code></td><td><div><p><strong>MANDATORY</strong>
Who the prescription is for
<a href="http://hl7.org/fhir/R4/patient.html">Patient</a></p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/medicationrequest.html#search">identifier</a></td><td><code>token</code></td><td><div><p>NZePS prescription-item business identifier (SCID plus item sequence number). Dispenses for the same prescription item share this identifier; it is distinct from the MDR dispense resource id.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/medicationrequest.html#search">status</a></td><td><code>token</code></td><td><div><p>Status filter, limited to active, on-hold, completed and stopped. If no permitted status remains, the result is empty.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>code</td><td><code>token</code></td><td><div><p>Medication code, forwarded unchanged to MDR for matching.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>location</td><td><code>reference</code></td><td><div><p>Facility search value, forwarded unchanged to MDR for matching.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>_count</td><td><code>number</code></td><td><div><p>Integer from 0 to 1000. With _count=0, the response contains Bundle.total and no medication entries. Otherwise Bundle.total is omitted.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>ct</td><td><code>string</code></td><td><div><p>Continuation token returned in the next-page URL in Bundle.link. Request that URL to retrieve the next page; it includes ct and the search parameters.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>authoredon</td><td><code>date</code></td><td><div><p>Prescription date filter.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>_sort</td><td><code>string</code></td><td><div><p>Sort by authoredon or -authoredon. Default: -authoredon. Invalid values, repeated parameters and multiple sort fields return HTTP 400.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>_revinclude</td><td><code>string</code></td><td><div><p><strong>MANDATORY</strong>
Supply MedicationDispense:prescription so prescriptions and dispenses can be assessed together for confidentiality and facility opt-outs. Missing or unsupported values return HTTP 400.</p>
</div></td></tr></tbody></table></div><div class="col-lg-5"><span class="lead">Combined Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameters</th><th>Types</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/medicationrequest.html#search">patient</a></td><td><code>reference</code></td></tr></tbody></table></div></div></div></div></div><div class="panel panel-default"><div class="panel-heading"><h4 id="MedicationDispense1-7" class="panel-title"><span style="float: right;">Resource Conformance: unspecified </span>MedicationDispense</h4></div><div class="panel-body"><div class="container"><div class="row"><div class="col-lg-6"><span class="lead">Base System Profile</span><br/><a href="StructureDefinition-SDHRMedicationDispense.html">SDHRMedicationDispense</a></div><div class="col-lg-3"><span class="lead">Profile Conformance</span><br/><b>SHALL</b></div><div class="col-lg-3"><span class="lead">Reference Policy</span><br/></div></div><p/><div class="row"><div class="col-lg-6"><span class="lead">Interaction summary</span><br/><ul><li>Supports <code>read</code>, <code>search-type</code>.</li></ul></div></div><p/><div class="row"><div class="col-12"><span class="lead">Documentation</span><blockquote><div><p>Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role.</p>
</div></blockquote></div></div><div class="row"><div class="col-lg-7"><span class="lead">Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameter</th><th>Type</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/medicationdispense.html#search">patient</a></td><td><code>reference</code></td><td><div><p><strong>MANDATORY</strong>
Who the dispense is for
<a href="http://hl7.org/fhir/R4/patient.html">Patient</a></p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/medicationdispense.html#search">identifier</a></td><td><code>token</code></td><td><div><p>NZePS prescription-item business identifier (SCID plus item sequence number). Dispenses for the same prescription item share this identifier; it is distinct from the MDR dispense resource id.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/medicationdispense.html#search">status</a></td><td><code>token</code></td><td><div><p>Status filter, limited to completed. If no permitted status remains, the result is empty.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>code</td><td><code>token</code></td><td><div><p>Medication code, forwarded unchanged to MDR for matching.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>location</td><td><code>reference</code></td><td><div><p>Facility search value, forwarded unchanged to MDR for matching.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>_count</td><td><code>number</code></td><td><div><p>Integer from 0 to 1000. With _count=0, the response contains Bundle.total and no medication entries. Otherwise Bundle.total is omitted.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>ct</td><td><code>string</code></td><td><div><p>Continuation token returned in the next-page URL in Bundle.link. Request that URL to retrieve the next page; it includes ct and the search parameters.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>whenprepared</td><td><code>date</code></td><td><div><p>Dispense preparation date filter.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>whenhandedover</td><td><code>date</code></td><td><div><p>Dispense handover date filter.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>_sort</td><td><code>string</code></td><td><div><p>Sort by whenprepared or whenhandedover, optionally prefixed with - for descending order. Default: -whenprepared. Invalid values, repeated parameters and multiple sort fields return HTTP 400.</p>
</div></td></tr><tr><td><b>SHALL</b></td><td>_include</td><td><code>string</code></td><td><div><p><strong>MANDATORY</strong>
Supply MedicationDispense:prescription so prescriptions and dispenses can be assessed together for confidentiality and facility opt-outs. Missing or unsupported values return HTTP 400.</p>
</div></td></tr></tbody></table></div><div class="col-lg-5"><span class="lead">Combined Search Parameters</span><table class="table table-condensed table-hover"><thead><tr><th>Conformance</th><th>Parameters</th><th>Types</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href="http://hl7.org/fhir/R4/medicationdispense.html#search">patient</a></td><td><code>reference</code></td></tr></tbody></table></div></div></div></div></div></div>
</text>
<extension
url="https://fhir-ig.digital.health.nz/hnz-digital-tooling/StructureDefinition/resource-metadata-extension">
<extension url="licenseURL">
<valueUri
value="https://www.tewhatuora.govt.nz/assets/Our-health-system/Digital-health/Digital-Service-Hub/API-Access-and-Use-Agreement.docx"/>
</extension>
<extension url="externalDocs">
<valueUri value="https://fhir-ig.digital.health.nz/sdhr"/>
</extension>
<extension url="licenseName">
<valueString
value="Health New Zealand Digital Services Hub API Access and Use Agreement"/>
</extension>
<extension url="globalHeaders">
<extension
url="https://fhir-ig.digital.health.nz/hnz-digital-tooling/StructureDefinition/custom-headers-extension">
<extension url="key">
<valueString value="X-Correlation-Id"/>
</extension>
<extension url="value">
<valueUri
value="https://raw.githubusercontent.com/tewhatuora/schemas/main/shared-care/Correlation-Id.json"/>
</extension>
<extension url="required">
<valueBoolean value="false"/>
</extension>
</extension>
<extension
url="https://fhir-ig.digital.health.nz/hnz-digital-tooling/StructureDefinition/custom-headers-extension">
<extension url="key">
<valueString value="Request-Context"/>
</extension>
<extension url="value">
<valueUri
value="https://raw.githubusercontent.com/tewhatuora/schemas/main/shared-care/Request-Context.json"/>
</extension>
<extension url="required">
<valueBoolean value="true"/>
</extension>
</extension>
</extension>
</extension>
<url
value="https://fhir-ig.digital.health.nz/sdhr/CapabilityStatement/SDHRCapabilityStatement"/>
<version value="1.1.6"/>
<name value="SDHRCapabilityStatement"/>
<title value="NZ Shared Digital Health Record API"/>
<status value="draft"/>
<experimental value="false"/>
<date value="2024-04-15T01:15:23.3688326Z"/>
<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="NZ Shared Digital Health Record API Capability Statement"/>
<kind value="capability"/>
<software>
<name value="NZ Shared Digital Health Record API"/>
<version value="1.0.0"/>
</software>
<implementation>
<description
value="Health NZ | Te Whatu Ora NZ Shared Digital Health Record API"/>
<url value="https://api.sdhr.digital.health.nz/s2s"/>
</implementation>
<fhirVersion value="4.0.1"/>
<format value="application/fhir+json"/>
<rest>
<mode value="server"/>
<documentation
value="### Request-Context custom header
All FHIR API requests MUST include the HNZ request context *custom header* which supplies identifiers for the health user
and organisation, or system behind the API request.
This context is supplied using the 'Request-Context' custom HTTP header in the form of a base64-encoded JSON object.
The value of the header has differing forms based on the type of request being made, namely whether it is in a user context (e.g. a clinical user searching for patient records), or a system context (e.g. a system submitting data to the API in a bulk load scenario).
#### Requests with user context
| **Context property** | **Mandatory** | **Value** |
|:-------------------------|:------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------|
| `userIdentifier` | Yes | The userid of the user as authenticated by the PMS/health application |
| `secondaryIdentifier` | Yes | The secondary identifier for the user. Must be a JSON object with: `use` (one of `usual`, `official`, `temp`, `secondary`, `old`), `system` (must be `https://standards.digital.health.nz/ns/hpi-person-id`), and a non-empty `value` |
| `purposeOfUse` | Yes | Exactly one of `[ "TREAT", "ETREAT" ]`. For descriptions of the values, see [Audit Events](https://fhir-ig.digital.health.nz/auditevents/ValueSet-purposeofuse.html) |
| `userFullName` | Yes | Full name of the user of the PMS/health application. |
| `userRole` | Yes | Role of the user of the PMS/health application. Set to `"PROV"` (Provider) |
| `orgIdentifier` | Yes | The HPI Organisation Number for the organisation in which the API consumer application is deployed. Must match the format `G[A-Z0-9]{5}-[A-Z]` (e.g. `G00001-G`) |
| `facilityIdentifier` | Yes | The HPI Facility identifier for the facility where the record is being sourced / accessed. Must match the format `F[A-Z0-9]{5}-[A-Z]` (e.g. `FZZ999-B`) |
#### Requests with system context
| **Context property** | **Mandatory** | **Value** |
|:-------------------------|:------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------|
| `userIdentifier` | Yes | The oAuth clientId of the system submitting data to the API |
| `secondaryIdentifier` | No (forbidden) | Must not be included in system-context requests |
| `purposeOfUse` | Yes | Must be exactly `[ "RECORDMGT" ]`. For descriptions of the values, see [Audit Events](https://fhir-ig.digital.health.nz/auditevents/ValueSet-purposeofuse.html) |
| `userFullName` | Yes | Name of the PMS/health application. |
| `userRole` | Yes | Role of the PMS/health application. Set to `"110150"` (Application) |
| `orgIdentifier` | Yes | The HPI Organisation Number for the organisation in which the API consumer application is deployed. Must match the format `G[A-Z0-9]{5}-[A-Z]` (e.g. `G00001-G`) |
| `facilityIdentifier` | Yes | The HPI Facility identifier for the facility. Must match the format `F[A-Z0-9]{5}-[A-Z]` (e.g. `FZZ999-B`) |
A schema definition and examples for `Request-Context` can be [found here](https://github.com/tewhatuora/schemas/blob/main/json-schema/Request-Context.json)
#### Example Request-Context Header Payload for a clinical user searching for a patient's Conditions
**Base64 Encoded**
```
ewogICJ1c2VySWRlbnRpZmllciI6ICJwbXMtaWQtMTIzIiwKICAidXNlclJvbGUiOiAiUFJPViIsCiAgInNlY29uZGFyeUlkZW50aWZpZXIiOiB7CiAgICAidXNlIjogIm9mZmljaWFsIiwKICAgICJzeXN0ZW0iOiAiaHR0cHM6Ly9zdGFuZGFyZHMuZGlnaXRhbC5oZWFsdGgubnovbnMvaHBpLXBlcnNvbi1pZCIsCiAgICAidmFsdWUiOiAiOTlaWlpTIgogIH0sCiAgInB1cnBvc2VPZlVzZSI6IFsKICAgICJUUkVBVCIKICBdLAogICJ1c2VyRnVsbE5hbWUiOiAiQmV2ZXJseSBDcnVzaGVyIiwKICAib3JnSWRlbnRpZmllciI6ICJHMDAwMDEtRyIsCiAgImZhY2lsaXR5SWRlbnRpZmllciI6ICJGWlo5OTktQiIKfQ==
```
**Decoded JSON**
```json
{
"userIdentifier": "pms-id-123",
"userRole": "PROV",
"secondaryIdentifier": {
"use": "official",
"system": "https://standards.digital.health.nz/ns/hpi-person-id",
"value": "99ZZZS"
},
"purposeOfUse": [
"TREAT"
],
"userFullName": "Beverly Crusher",
"orgIdentifier": "G00001-G",
"facilityIdentifier": "FZZ999-B"
}
```
#### Example Request-Context Header Payload for a system submitting data to the API, where there is no end user
**Base64 Encoded**
```
ewogICAgInVzZXJJZGVudGlmaWVyIjogIjFiODIwMGQ3LTNhOGMtNGZiNi04ZTVjLWNlYzQ1NDA5OTlkNSIsCiAgICAidXNlclJvbGUiOiAiMTEwMTUwIiwKICAgICJwdXJwb3NlT2ZVc2UiOiBbCiAgICAgICAgIlJFQ09SRE1HVCIKICAgIF0sCiAgICAidXNlckZ1bGxOYW1lIjogIlNhbXBsZSBQTVMgSW50ZWdyYXRpb24gQXBwbGljYXRpb24iLAogICAgIm9yZ0lkZW50aWZpZXIiOiAiRzAwMDAxLUciLAogICAgImZhY2lsaXR5SWRlbnRpZmllciI6ICJGWlo5OTktQiIKfQ==
```
**Decoded JSON**
```json
{
"userIdentifier": "1b8200d7-3a8c-4fb6-8e5c-cec4540999d5",
"userRole": "110150",
"purposeOfUse": [
"RECORDMGT"
],
"userFullName": "Sample PMS Integration Application",
"orgIdentifier": "G00001-G",
"facilityIdentifier": "FZZ999-B"
}
```
### Mandatory search parameters
All FHIR API search requests must include the HNZ mandatory search parameters. These are listed in the Combined Search Parameters section of each resource below.
### Error status codes
#### Read (GET) Operation Statuses
|**Code**|**Meaning**|**Description**|
|:--:|:-----------------|:--|
|200|OK |The request was successful, and the response body contains the representation requested|
|302|FOUND |A common redirect response; you can GET the representation at the URI in the Location response header|
|304|NOT MODIFIED |Your client's cached version of the representation is still up to date|
|400|BAD REQUEST |Missing or bad `Request-Context` custom header; FHIR request payload does not validate against Implementation Guide|
|401|UNAUTHORIZED |The supplied credentials, if any, are not sufficient to access the resource|
|403|FORBIDDEN |Insufficient privilege or participation denial. See [global denial](./OperationOutcome-OperationOutcomeGlobalDenyExample.html) and [global denial due to patient-deceased opt-out](./OperationOutcome-OperationOutcomeGlobalDenyDeceasedExample.html).|
|404|NOT FOUND |The requested representation was not found. Retrying this request is unlikely to be successful|
|429|TOO MANY REQUESTS |Your application is sending too many simultaneous requests|
|500|SERVER ERROR |An internal server error prevented return of the representation response|
|503|SERVICE UNAVAILABLE|We are temporarily unable to return the representation. Please wait and try again later|
#### Search (GET) Operation Statuses
|**Code**|**Meaning** |**OperationOutcome** in response?|**Description**|
|:--:|:-----------------|:----------------------------------|:----------------------------------|
|200|OK |Yes, When there are additional messages about a match result|The request was successful, and the response body contains the representation requested|
|302|FOUND |No |A common redirect response; you can GET the representation at the URI in the Location response header|
|400|BAD REQUEST |Yes|Missing or bad `Request-Context` custom header;<br>FHIR request payload does not validate against Implementation Guide|
|401|UNAUTHORIZED |Yes|The supplied credentials, if any, are not sufficient to access the resource|
|403|FORBIDDEN |Yes|Insufficient privilege or participation denial. See [OperationOutcome-APIError-Unauthorised](./OperationOutcome-APIError-Unauthorised.html), [global denial](./OperationOutcome-OperationOutcomeGlobalDenyExample.html), and [global denial due to patient-deceased opt-out](./OperationOutcome-OperationOutcomeGlobalDenyDeceasedExample.html).|
|429|TOO MANY REQUESTS |No |Your application is sending too many simultaneous requests|
|500|SERVER ERROR |No |An internal server error prevented return of the representation response|
|503|SERVICE UNAVAILABLE|No |The server is temporarily unable to return the representation. Please wait and try again later|
#### Update or Create (POST or PUT) Operation Statuses
|**Code**|**Meaning** |**OperationOutcome** in response?|**Description**|
|:--:|:-----------------|:----------------------------------|:----------------------------------|
|200|OK |Yes, When there are additional messages about an operation|The request was successful, and the response body contains the representation requested|
|201|CREATED |No|The request was successful, and the response body contains the representation created|
|400|BAD REQUEST |Yes|Missing or bad `Request-Context` custom header;<br>FHIR request payload does not validate against Implementation Guide|
|401|UNAUTHORIZED |Yes|The supplied credentials, if any, are not sufficient to access the resource|
|403|FORBIDDEN |Yes|Insufficient privilege to access the requested FHIR resource/operation. See [OperationOutcome-APIError-Unauthorised](./OperationOutcome-APIError-Unauthorised.html)|
|404|NOT FOUND |Yes|The update target does not exist. Updating a missing resource does not create it|
|409|CONFLICT |Yes|A concurrent write or resource lock prevented the operation|
|429|TOO MANY REQUESTS |Yes |Your application is sending too many simultaneous requests|
|500|SERVER ERROR |Yes |An internal server error prevented return of the representation response|
|503|SERVICE UNAVAILABLE|No |The server is temporarily unable to return the representation. Please wait and try again later|
### Non existent API endpoints
When a consumer attempts to call a non-existent API end point, respond
with a **501 Not Implemented** status code.
### API Rate Limits
API rate limiting is enforced on a per client basis, and the status of the rate limit is communicated via the following HTTP response headers:
| **Header name** | **Description** |
|:----------------------|:-------------------------------------------------|
| x-ratelimit-remaining | The amount of available quota |
| x-ratelimit-limit | The maximum available requests per window |
| x-ratelimit-reset | The remaining time, in milliseconds, until a new window starts |
The API client **MUST** monitor these headers and ensure that they do not exceed the quota expressed in the `x-ratelimit-limit` header before the time window expressed in `x-ratelimit-reset`.
If the rate limit is exceeded, the API will respond with a **429 Too Many Requests** status code and the [Rate Limit OperationOutcome](./OperationOutcome-OperationOutcomeRateLimitExceeded.json.html).
| **Usage plan** | **Rate limits** |
|:----------------------|:-------------------------------------------------|
| SDHR Gold | 400 requests per second, per client |
| SDHR Silver | 50 requests per second, per client |
| SDHR Bronze | 10 requests per second, per client |
Where the rate limit is exceeded as part of normal operations, the API client can request an increased quota by contacting the SDHR service desk portal."/>
<security>
<extension
url="http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris">
<extension url="token">
<valueUri
value="https://ppd.auth.services.health.nz/realms/hnz-integration/protocol/openid-connect/token"/>
</extension>
<extension url="authorize">
<valueUri
value="https://ppd.auth.services.health.nz/realms/hnz-integration/protocol/openid-connect/authorize"/>
</extension>
</extension>
<extension
url="http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities">
<valueCode value="client-confidential-symmetric"/>
</extension>
<cors value="true"/>
<service>
<coding>
<code value="SMART-on-FHIR"/>
</coding>
</service>
<description value="OAuth 2.0 - Client Credential flow."/>
</security>
<resource>
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination">
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation">
<valueCode value="SHALL"/>
</extension>
<extension url="required">
<valueString value="patient"/>
</extension>
</extension>
<type value="AllergyIntolerance"/>
<profile
value="https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAllergyIntolerance"/>
<documentation
value="Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role."/>
<interaction>
<code value="read"/>
</interaction>
<interaction>
<code value="create"/>
</interaction>
<interaction>
<code value="update"/>
</interaction>
<interaction>
<code value="search-type"/>
</interaction>
<interaction>
<code value="delete"/>
</interaction>
<searchParam>
<name value="patient"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-patient"/>
<type value="reference"/>
<documentation
value="MANDATORY
Who the sensitivity is for
[Patient](http://hl7.org/fhir/R4/patient.html)"/>
</searchParam>
<searchParam>
<name value="category"/>
<definition
value="http://hl7.org/fhir/SearchParameter/AllergyIntolerance-category"/>
<type value="token"/>
<documentation
value="Must be one of
* food
* medication
* environment
* biologic
[AllergyIntolerance Category ValueSet](http://hl7.org/fhir/ValueSet/allergy-intolerance-category)"/>
</searchParam>
<searchParam>
<name value="clinical-status"/>
<definition
value="http://hl7.org/fhir/SearchParameter/AllergyIntolerance-clinical-status"/>
<type value="token"/>
<documentation
value="Must be one of
* active
* inactive
* resolved
[AllergyIntolerance Clinical Status ValueSet](http://hl7.org/fhir/R4/valueset-allergyintolerance-clinical.html)"/>
</searchParam>
<searchParam>
<name value="code"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-code"/>
<type value="token"/>
<documentation
value="Code that identifies the allergy or intolerance
[AllergyIntolerance Code ValueSet](http://hl7.org/fhir/ValueSet/allergyintolerance-code)"/>
</searchParam>
<searchParam>
<name value="identifier"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-identifier"/>
<type value="token"/>
<documentation
value="A unique identifier assigned to this resource."/>
</searchParam>
<searchParam>
<name value="recorder"/>
<definition
value="http://hl7.org/fhir/SearchParameter/AllergyIntolerance-recorder"/>
<type value="reference"/>
<documentation
value="Who recorded the sensitivity
[AllergyIntolerance.recorder](http://hl7.org/fhir/R4/allergyintolerance-definitions.html#AllergyIntolerance.recorder)"/>
</searchParam>
<searchParam>
<name value="severity"/>
<definition value="http://hl7.org/fhir/SearchParameter/severity"/>
<type value="token"/>
<documentation
value="mild | moderate | severe (of event as a whole)."/>
</searchParam>
<searchParam>
<name value="clientlastupdated"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/SearchParameter/allergyintolerance-clientlastupdated"/>
<type value="date"/>
<documentation
value="The ClientLastUpdated extension value. This date parameter can also be used with `_sort=clientlastupdated` or `_sort=-clientlastupdated`."/>
</searchParam>
<searchParam>
<name value="_lastUpdated"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Resource-lastUpdated"/>
<type value="date"/>
<documentation value="When the resource version last changed"/>
</searchParam>
</resource>
<resource>
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination">
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation">
<valueCode value="SHALL"/>
</extension>
<extension url="required">
<valueString value="patient"/>
</extension>
</extension>
<type value="Condition"/>
<profile
value="https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRCondition"/>
<documentation
value="Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role."/>
<interaction>
<code value="read"/>
</interaction>
<interaction>
<code value="create"/>
</interaction>
<interaction>
<code value="update"/>
</interaction>
<interaction>
<code value="search-type"/>
</interaction>
<interaction>
<code value="delete"/>
</interaction>
<searchInclude value="Condition:encounter"/>
<searchParam>
<name value="patient"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-patient"/>
<type value="reference"/>
<documentation value="**MANDATORY**
Who has the condition?"/>
</searchParam>
<searchParam>
<name value="category"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Condition-category"/>
<type value="token"/>
<documentation value="The category of the condition"/>
</searchParam>
<searchParam>
<name value="code"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-code"/>
<type value="token"/>
<documentation value="The code for the condition"/>
</searchParam>
<searchParam>
<name value="encounter"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Condition-encounter"/>
<type value="reference"/>
<documentation value="Encounter associated with the condition"/>
</searchParam>
<searchParam>
<name value="identifier"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-identifier"/>
<type value="token"/>
<documentation
value="A unique identifier assigned to this resource."/>
</searchParam>
<searchParam>
<name value="onset-date"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Condition-onset-date"/>
<type value="date"/>
<documentation value="Date the condition started"/>
</searchParam>
<searchParam>
<name value="severity"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Condition-severity"/>
<type value="token"/>
<documentation value="The severity of the condition"/>
</searchParam>
<searchParam>
<name value="subject"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Condition-subject"/>
<type value="reference"/>
<documentation value="Who has the condition?"/>
</searchParam>
<searchParam>
<name value="highlighted"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/SearchParameter/condition-highlighted"/>
<type value="token"/>
<documentation
value="Search for conditions flagged as highlighted in the SDHRCondition profile"/>
</searchParam>
<searchParam>
<name value="long-term-condition"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/SearchParameter/condition-long-term-condition"/>
<type value="token"/>
<documentation
value="Search for conditions flagged as long term in the SDHRCondition profile"/>
</searchParam>
<searchParam>
<name value="clientlastupdated"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/SearchParameter/condition-clientlastupdated"/>
<type value="date"/>
<documentation
value="The ClientLastUpdated extension value. This date parameter can also be used with `_sort=clientlastupdated` or `_sort=-clientlastupdated`."/>
</searchParam>
<searchParam>
<name value="_lastUpdated"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Resource-lastUpdated"/>
<type value="date"/>
<documentation value="When the resource version last changed."/>
</searchParam>
</resource>
<resource>
<type value="AuditEvent"/>
<profile
value="https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAuditEvent"/>
<supportedProfile
value="https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAuditEvent"/>
<documentation
value="AuditEvent supports DRAFT custom operations for data viewer application verification workflows."/>
<operation>
<name value="verification-samples"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRVerificationSamplesOperation"/>
<documentation
value="Returns sampled AuditEvent resources that are still outstanding for verification by the authenticated data viewer application. Successful requests return a searchset Bundle, which may be empty. Supports optional `_count` and `_getpagesoffset` query parameters for paging. Generic AuditEvent interactions are not supported."/>
</operation>
<operation>
<name value="verification-submissions"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRVerificationSubmissionsOperation"/>
<documentation
value="DRAFT OPERATION: Accepts a Parameters payload containing one or more verification decisions for sampled AuditEvent resources."/>
</operation>
</resource>
<resource>
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination">
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation">
<valueCode value="SHALL"/>
</extension>
<extension url="required">
<valueString value="patient"/>
</extension>
</extension>
<type value="Observation"/>
<profile
value="https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRObservation"/>
<documentation
value="Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role."/>
<interaction>
<code value="read"/>
</interaction>
<interaction>
<code value="create"/>
</interaction>
<interaction>
<code value="update"/>
</interaction>
<interaction>
<code value="search-type"/>
</interaction>
<interaction>
<code value="delete"/>
</interaction>
<searchParam>
<name value="patient"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-patient"/>
<type value="reference"/>
<documentation
value="**MANDATORY**
Who the observation is for
[Patient](http://hl7.org/fhir/R4/patient.html)"/>
</searchParam>
<searchParam>
<name value="category"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Observation-category"/>
<type value="token"/>
<documentation value="The classification of the type of observation"/>
</searchParam>
<searchParam>
<name value="code"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-code"/>
<type value="token"/>
<documentation
value="Describes what was observed. Sometimes this is called the observation 'name'"/>
</searchParam>
<searchParam>
<name value="date"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-date"/>
<type value="date"/>
<documentation
value="Observation.effective
Obtained date/time. If the obtained element is a period, a date that falls in the period"/>
</searchParam>
<searchParam>
<name value="encounter"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-encounter"/>
<type value="reference"/>
<documentation
value="The Encounter resource associated with the Observation."/>
</searchParam>
<searchParam>
<name value="identifier"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-identifier"/>
<type value="token"/>
<documentation
value="A unique identifier assigned to this resource."/>
</searchParam>
<searchParam>
<name value="performer"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Observation-performer"/>
<type value="reference"/>
<documentation value="Who performed the observation"/>
</searchParam>
<searchParam>
<name value="status"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Observation-status"/>
<type value="token"/>
<documentation value="The status of the observation"/>
</searchParam>
<searchParam>
<name value="subject"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Observation-subject"/>
<type value="reference"/>
<documentation value="The subject that the observation is about"/>
</searchParam>
<searchParam>
<name value="value-concept"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Observation-value-concept"/>
<type value="token"/>
<documentation
value="The value of the observation, if the value is a CodeableConcept"/>
</searchParam>
<searchParam>
<name value="value-date"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Observation-value-date"/>
<type value="date"/>
<documentation
value="The value of the observation, if the value is a date or period of time"/>
</searchParam>
<searchParam>
<name value="value-quantity"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Observation-value-quantity"/>
<type value="quantity"/>
<documentation
value="The value of the observation, if the value is a Quantity, or a SampledData (just search on the bounds of the values in sampled data)"/>
</searchParam>
<searchParam>
<name value="value-string"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Observation-value-string"/>
<type value="string"/>
<documentation
value="The value of the observation, if the value is a string, and also searches in CodeableConcept.text"/>
</searchParam>
<searchParam>
<name value="clientlastupdated"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/SearchParameter/observation-clientlastupdated"/>
<type value="date"/>
<documentation
value="The ClientLastUpdated extension value. This date parameter can also be used with `_sort=clientlastupdated` or `_sort=-clientlastupdated`."/>
</searchParam>
<searchParam>
<name value="_lastUpdated"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Resource-lastUpdated"/>
<type value="date"/>
<documentation value="When the resource version last changed."/>
</searchParam>
</resource>
<resource>
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination">
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation">
<valueCode value="SHALL"/>
</extension>
<extension url="required">
<valueString value="patient"/>
</extension>
</extension>
<type value="Immunization"/>
<profile
value="https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRImmunization"/>
<documentation
value="Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role."/>
<interaction>
<code value="read"/>
</interaction>
<interaction>
<code value="search-type"/>
</interaction>
<searchParam>
<name value="patient"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-patient"/>
<type value="reference"/>
<documentation
value="**MANDATORY**
Who the immunization is for
[Patient](http://hl7.org/fhir/R4/patient.html)"/>
</searchParam>
<searchParam>
<name value="date"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Immunization-date"/>
<type value="date"/>
<documentation
value="Vaccination (occurrence) date. Comparators eq, ge, gt, le, lt are supported; two `date` parameters may be combined for a range."/>
</searchParam>
<searchParam>
<name value="location"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Immunization-location"/>
<type value="reference"/>
<documentation
value="Facility (HPI) where the vaccination was administered."/>
</searchParam>
<searchParam>
<name value="vaccine-code"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Immunization-vaccine-code"/>
<type value="token"/>
<documentation
value="Vaccine product administered. Supports `system|code` or bare `code`, and the `:text` modifier for name search."/>
</searchParam>
<searchParam>
<name value="target-disease"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Immunization-target-disease"/>
<type value="token"/>
<documentation
value="Disease targeted by the vaccination (protocolApplied.targetDisease, SNOMED)."/>
</searchParam>
<searchParam>
<name value="status"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Immunization-status"/>
<type value="token"/>
<documentation
value="Immunisation event status. Records with status `entered-in-error` are excluded from search results."/>
</searchParam>
<searchParam>
<name value="status-reason"/>
<definition
value="http://hl7.org/fhir/SearchParameter/Immunization-status-reason"/>
<type value="token"/>
<documentation value="Reason a vaccination was not administered."/>
</searchParam>
<searchParam>
<name value="product"/>
<type value="token"/>
<documentation
value="Administered product from the AIR administered-product extension, distinct from vaccine-code. Supports system|code or bare code, and :text for case-insensitive substring matching against text or coding display."/>
</searchParam>
<searchParam>
<name value="_sort"/>
<type value="string"/>
<documentation
value="Sort by occurrence date: date for ascending or -date for descending. Default: -date."/>
</searchParam>
</resource>
<resource>
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination">
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation">
<valueCode value="SHALL"/>
</extension>
<extension url="required">
<valueString value="patient"/>
</extension>
</extension>
<type value="MedicationRequest"/>
<profile
value="https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRMedicationRequest"/>
<documentation
value="Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role."/>
<interaction>
<code value="read"/>
</interaction>
<interaction>
<code value="search-type"/>
</interaction>
<searchRevInclude value="MedicationDispense:prescription"/>
<searchParam>
<name value="patient"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-patient"/>
<type value="reference"/>
<documentation
value="**MANDATORY**
Who the prescription is for
[Patient](http://hl7.org/fhir/R4/patient.html)"/>
</searchParam>
<searchParam>
<name value="identifier"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-identifier"/>
<type value="token"/>
<documentation
value="NZePS prescription-item business identifier (SCID plus item sequence number). Dispenses for the same prescription item share this identifier; it is distinct from the MDR dispense resource id."/>
</searchParam>
<searchParam>
<name value="status"/>
<definition
value="http://hl7.org/fhir/SearchParameter/medications-status"/>
<type value="token"/>
<documentation
value="Status filter, limited to active, on-hold, completed and stopped. If no permitted status remains, the result is empty."/>
</searchParam>
<searchParam>
<name value="code"/>
<type value="token"/>
<documentation
value="Medication code, forwarded unchanged to MDR for matching."/>
</searchParam>
<searchParam>
<name value="location"/>
<type value="reference"/>
<documentation
value="Facility search value, forwarded unchanged to MDR for matching."/>
</searchParam>
<searchParam>
<name value="_count"/>
<type value="number"/>
<documentation
value="Integer from 0 to 1000. With _count=0, the response contains Bundle.total and no medication entries. Otherwise Bundle.total is omitted."/>
</searchParam>
<searchParam>
<name value="ct"/>
<type value="string"/>
<documentation
value="Continuation token returned in the next-page URL in Bundle.link. Request that URL to retrieve the next page; it includes ct and the search parameters."/>
</searchParam>
<searchParam>
<name value="authoredon"/>
<type value="date"/>
<documentation value="Prescription date filter."/>
</searchParam>
<searchParam>
<name value="_sort"/>
<type value="string"/>
<documentation
value="Sort by authoredon or -authoredon. Default: -authoredon. Invalid values, repeated parameters and multiple sort fields return HTTP 400."/>
</searchParam>
<searchParam>
<name value="_revinclude"/>
<type value="string"/>
<documentation
value="**MANDATORY**
Supply MedicationDispense:prescription so prescriptions and dispenses can be assessed together for confidentiality and facility opt-outs. Missing or unsupported values return HTTP 400."/>
</searchParam>
</resource>
<resource>
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination">
<extension
url="http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation">
<valueCode value="SHALL"/>
</extension>
<extension url="required">
<valueString value="patient"/>
</extension>
</extension>
<type value="MedicationDispense"/>
<profile
value="https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRMedicationDispense"/>
<documentation
value="Note that the supported interactions of the API will vary per API Consumer, depending on the consuming system's role."/>
<interaction>
<code value="read"/>
</interaction>
<interaction>
<code value="search-type"/>
</interaction>
<searchInclude value="MedicationDispense:prescription"/>
<searchParam>
<name value="patient"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-patient"/>
<type value="reference"/>
<documentation
value="**MANDATORY**
Who the dispense is for
[Patient](http://hl7.org/fhir/R4/patient.html)"/>
</searchParam>
<searchParam>
<name value="identifier"/>
<definition
value="http://hl7.org/fhir/SearchParameter/clinical-identifier"/>
<type value="token"/>
<documentation
value="NZePS prescription-item business identifier (SCID plus item sequence number). Dispenses for the same prescription item share this identifier; it is distinct from the MDR dispense resource id."/>
</searchParam>
<searchParam>
<name value="status"/>
<definition
value="http://hl7.org/fhir/SearchParameter/medications-status"/>
<type value="token"/>
<documentation
value="Status filter, limited to completed. If no permitted status remains, the result is empty."/>
</searchParam>
<searchParam>
<name value="code"/>
<type value="token"/>
<documentation
value="Medication code, forwarded unchanged to MDR for matching."/>
</searchParam>
<searchParam>
<name value="location"/>
<type value="reference"/>
<documentation
value="Facility search value, forwarded unchanged to MDR for matching."/>
</searchParam>
<searchParam>
<name value="_count"/>
<type value="number"/>
<documentation
value="Integer from 0 to 1000. With _count=0, the response contains Bundle.total and no medication entries. Otherwise Bundle.total is omitted."/>
</searchParam>
<searchParam>
<name value="ct"/>
<type value="string"/>
<documentation
value="Continuation token returned in the next-page URL in Bundle.link. Request that URL to retrieve the next page; it includes ct and the search parameters."/>
</searchParam>
<searchParam>
<name value="whenprepared"/>
<type value="date"/>
<documentation value="Dispense preparation date filter."/>
</searchParam>
<searchParam>
<name value="whenhandedover"/>
<type value="date"/>
<documentation value="Dispense handover date filter."/>
</searchParam>
<searchParam>
<name value="_sort"/>
<type value="string"/>
<documentation
value="Sort by whenprepared or whenhandedover, optionally prefixed with - for descending order. Default: -whenprepared. Invalid values, repeated parameters and multiple sort fields return HTTP 400."/>
</searchParam>
<searchParam>
<name value="_include"/>
<type value="string"/>
<documentation
value="**MANDATORY**
Supply MedicationDispense:prescription so prescriptions and dispenses can be assessed together for confidentiality and facility opt-outs. Missing or unsupported values return HTTP 400."/>
</searchParam>
</resource>
<interaction>
<code value="search-system"/>
</interaction>
<interaction>
<code value="transaction"/>
</interaction>
<interaction>
<code value="batch"/>
</interaction>
<operation>
<name value="participate"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRParticipateOperation"/>
<documentation
value="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](./Parameters-ParametersDoNotParticipate.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-ParametersParticipate.html) : 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](./Parameters-ParametersParticipateRecordWithheld.html) : 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](./Parameters-ParametersParticipateRecordReleased.html) : 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.
When `participationIndicator` is `false`, SDHR records the facility opt-out and archives the patient's active contributed resources from the supplied facility. Archived resources are not returned by normal search or read interactions.
For an opt-in request using pull-based acquisition, the 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 updates consent without triggering a historic load.
When 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).
The operation will return an OperationOutcome resource indicating the result of the operation."/>
</operation>
<operation>
<name value="hnz-participate"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRHNZParticipateOperation"/>
<documentation
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 (patient choice)](./Parameters-ParametersHNZParticipateOptOut.html) : This example shows a global opt-out using reason `patient-choice`.
- [Parameters resource for total non-participation (patient deceased)](./Parameters-ParametersHNZParticipateOptOutDeceased.html) : This example shows a global opt-out using reason `patient-deceased`.
- [Parameters resource for total non-participation (imported external consent)](./Parameters-ParametersHNZParticipateOptOutImportedExternalConsent.html) : This example shows a global opt-out using reason `imported-external-consent`.
- [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.
When `hnzParticipationIndicator` is `false`, SDHR requires `hnzOptOutReasonCode`, records the global opt-out reason, and archives the patient's active contributed resources across all facilities. Archived resources are not returned by normal search or read interactions.
When 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).
For 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.
When 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).
The operation will return an OperationOutcome resource indicating the result of the operation."/>
</operation>
<operation>
<name value="hnz-domain-participate"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRHNZDomainParticipateOperation"/>
<documentation
value="Records one or more domain choices on exactly one patient's Consent through authorised Health NZ channels. Supply one patient and one domains parameter with named boolean parts. Linked Consents are unchanged; any linked domain deny blocks access for the group. Global participation remains managed through $hnz-participate."/>
</operation>
<operation>
<name value="hnz-participation-status"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRHNZParticipationStatusOperation"/>
<documentation
value="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, the global opt-out reason when applicable, 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.
This operation requires the SMART on FHIR scope `https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRHNZParticipationStatusOperation`.
For an example response payload for this operation see:
- [Parameters resource for participation status response](./Parameters-ParametersParticipationStatusResponse.html) : This example shows the `Parameters` resource returned by the operation when participation status information is found for a patient.
- [Parameters resource for participation status response after opt-out](./Parameters-ParametersParticipationStatusEnrolmentResponse.html) : This example shows an enrolled patient with archived records after opting out.
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."/>
</operation>
<operation>
<name value="participation-status"/>
<definition
value="https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRParticipationStatusOperation"/>
<documentation
value="This operation allows Shared Electronic Health Record (SEHR) systems to retrieve a patient's Shared Digital Health Record participation status.
For an example response payload for this operation see:
- [Parameters resource for participation status response - not participating](./Parameters-ParametersParticipationStatusNotParticipatingResponse.html) : This example shows the `Parameters` resource returned when the patient is not participating in the Shared Digital Health Record service.
- [Parameters resource for participation status response - participating](./Parameters-ParametersParticipationStatusParticipatingResponse.html) : This example shows the `Parameters` resource returned when the patient is participating 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/$participation-status`).
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.
This operation requires the SMART on FHIR scope `https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRParticipationStatusOperation`.
The operation returns a `Parameters` resource containing only `hnzParticipationIndicator`. A patient with no recorded global participation preference is considered to be participating and returns `true`."/>
</operation>
</rest>
</CapabilityStatement>