Health NZ | Te Whatu Ora FHIR Screening Implementation Guide
1.0.2 - normative+trial-use
Health NZ | Te Whatu Ora FHIR Screening Implementation Guide
1.0.2 - normative+trial-use
Health NZ | Te Whatu Ora FHIR Screening Implementation Guide - Local Development build (v1.0.2) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| Draft as of 2024-05-03 |
{
"resourceType" : "CapabilityStatement",
"id" : "FHIRScreeningCapabilityStatement",
"meta" : {
"profile" : [
🔗 "https://fhir-ig.digital.health.nz/hnz-digital-tooling/StructureDefinition/hnz-capability-statement"
]
},
"text" : {
"status" : "extensions",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: CapabilityStatement FHIRScreeningCapabilityStatement</b></p><a name=\"FHIRScreeningCapabilityStatement\"> </a><a name=\"hcFHIRScreeningCapabilityStatement\"> </a><a name=\"FHIRScreeningCapabilityStatement-en-NZ\"> </a><h2 id=\"title\">National Screening FHIR API Capability Statement</h2><ul><li>Implementation Guide Version: 1.0.2 </li><li>FHIR Version: 4.0.1 </li><li>Supported Formats: <code>json</code></li><li>Supported Patch Formats: </li><li>Published on: 2024-05-03 </li><li>Published by: Health New Zealand | Te Whatu Ora </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 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><div class=\"lead\"><em>Summary of System-wide Interactions</em></div><ul><li>Supports the <code>search-system</code>interaction described as follows:<div><h3>Request-Context custom header</h3>\n<p>All screening FHIR API requests must include the HNZ request context <em>custom header</em> supplying identifiers for the health user\nand organisation behind the API request.</p>\n<p>This context is supplied using the 'Request-Context' custom header in the form of a base64-encoded JSON object.</p>\n<table class=\"grid\">\n<thead>\n<tr>\n<th align=\"left\"><strong>Context property</strong></th>\n<th align=\"left\"><strong>Value</strong></th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td align=\"left\"><code>userIdentifier</code></td>\n<td align=\"left\">The userid of the user as authenticated by the PMS/health application (REQUIRED)</td>\n</tr>\n<tr>\n<td align=\"left\"><code>purposeOfUse</code></td>\n<td align=\"left\">Set to <code>"SCREENING"</code> (REQUIRED)</td>\n</tr>\n<tr>\n<td align=\"left\"><code>userFullName</code></td>\n<td align=\"left\">Full name of the user of the PMS/health application. (REQUIRED)</td>\n</tr>\n<tr>\n<td align=\"left\"><code>hpiPractitioner</code></td>\n<td align=\"left\">The Common Person Number (aka HPI Practitioner identifier) of the practitioner using the application (REQUIRED)</td>\n</tr>\n<tr>\n<td align=\"left\"><code>hpiOrganisation</code> or <code>hpiFacility</code></td>\n<td align=\"left\">HPI identifier for the organisation or facility where the user is located -- at least one is REQUIRED</td>\n</tr>\n</tbody>\n</table>\n<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-v2.json\">found here</a></p>\n<h3>Error status codes</h3>\n<h4>Read (GET) Operation Statuses</h4>\n<table class=\"grid\">\n<thead>\n<tr>\n<th align=\"center\"><strong>Code</strong></th>\n<th align=\"left\"><strong>Meaning</strong></th>\n<th align=\"left\"><strong>Description</strong></th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td align=\"center\">200</td>\n<td align=\"left\">OK</td>\n<td align=\"left\">The request was successful, and the response body contains the representation requested</td>\n</tr>\n<tr>\n<td align=\"center\">302</td>\n<td align=\"left\">FOUND</td>\n<td align=\"left\">A common redirect response; you can GET the representation at the URI in the Location response header</td>\n</tr>\n<tr>\n<td align=\"center\">304</td>\n<td align=\"left\">NOT MODIFIED</td>\n<td align=\"left\">Your client's cached version of the representation is still up to date</td>\n</tr>\n<tr>\n<td align=\"center\">400</td>\n<td align=\"left\">BAD REQUEST</td>\n<td align=\"left\">Missing or bad <code>Security-Context</code> custom header; FHIR request payload does not validate against Implementation Guide</td>\n</tr>\n<tr>\n<td align=\"center\">401</td>\n<td align=\"left\">UNAUTHORIZED</td>\n<td align=\"left\">The supplied credentials, if any, are not sufficient to access the resource</td>\n</tr>\n<tr>\n<td align=\"center\">403</td>\n<td align=\"left\">FORBIDDEN</td>\n<td align=\"left\">Insufficient privilege to access the requested FHIR resource/operation</td>\n</tr>\n<tr>\n<td align=\"center\">404</td>\n<td align=\"left\">NOT FOUND</td>\n<td align=\"left\">The requested representation was not found. Retrying this request is unlikely to be successful</td>\n</tr>\n<tr>\n<td align=\"center\">429</td>\n<td align=\"left\">TOO MANY REQUESTS</td>\n<td align=\"left\">Your application is sending too many simultaneous requests</td>\n</tr>\n<tr>\n<td align=\"center\">500</td>\n<td align=\"left\">SERVER ERROR</td>\n<td align=\"left\">An internal server error prevented return of the representation response</td>\n</tr>\n<tr>\n<td align=\"center\">503</td>\n<td align=\"left\">SERVICE UNAVAILABLE</td>\n<td align=\"left\">We are temporarily unable to return the representation. Please wait and try again later</td>\n</tr>\n</tbody>\n</table>\n<h4>Search (GET) Operation Statuses</h4>\n<table class=\"grid\">\n<thead>\n<tr>\n<th align=\"center\"><strong>Code</strong></th>\n<th align=\"left\"><strong>Meaning</strong></th>\n<th align=\"left\"><strong>OperationOutcome</strong> in response?</th>\n<th align=\"left\"><strong>Description</strong></th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td align=\"center\">200</td>\n<td align=\"left\">OK</td>\n<td align=\"left\">Yes, when there are additional messages about a match result</td>\n<td align=\"left\">The request was successful, and the response body contains the representation requested</td>\n</tr>\n<tr>\n<td align=\"center\">302</td>\n<td align=\"left\">FOUND</td>\n<td align=\"left\">No</td>\n<td align=\"left\">A common redirect response; you can GET the representation at the URI in the Location response header</td>\n</tr>\n<tr>\n<td align=\"center\">400</td>\n<td align=\"left\">BAD REQUEST</td>\n<td align=\"left\">Missing or bad <code>Security-Context</code> custom header; FHIR request payload does not validate against Implementation Guide</td>\n<td align=\"left\"/>\n</tr>\n<tr>\n<td align=\"center\">401</td>\n<td align=\"left\">UNAUTHORIZED</td>\n<td align=\"left\">The supplied credentials, if any, are not sufficient to access the resource</td>\n<td align=\"left\"/>\n</tr>\n<tr>\n<td align=\"center\">403</td>\n<td align=\"left\">FORBIDDEN</td>\n<td align=\"left\">Insufficient privilege to access the requested FHIR resource/operation</td>\n<td align=\"left\"/>\n</tr>\n<tr>\n<td align=\"center\">429</td>\n<td align=\"left\">TOO MANY REQUESTS</td>\n<td align=\"left\">No</td>\n<td align=\"left\">Your application is sending too many simultaneous requests</td>\n</tr>\n<tr>\n<td align=\"center\">500</td>\n<td align=\"left\">SERVER ERROR</td>\n<td align=\"left\">No</td>\n<td align=\"left\">An internal server error prevented return of the representation response</td>\n</tr>\n<tr>\n<td align=\"center\">503</td>\n<td align=\"left\">SERVICE UNAVAILABLE</td>\n<td align=\"left\">No</td>\n<td align=\"left\">The server is temporarily unable to return the representation. Please wait and try again later</td>\n</tr>\n</tbody>\n</table>\n<h4>Create (POST or PUT) Operation Statuses</h4>\n<table class=\"grid\">\n<thead>\n<tr>\n<th align=\"center\"><strong>Code</strong></th>\n<th align=\"left\"><strong>Meaning</strong></th>\n<th align=\"left\"><strong>Description</strong></th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td align=\"center\">200</td>\n<td align=\"left\">OK</td>\n<td align=\"left\">The request was successful, and the resource was updated. The response body contains the updated representation</td>\n</tr>\n<tr>\n<td align=\"center\">201</td>\n<td align=\"left\">CREATED</td>\n<td align=\"left\">The request was successful, a new resource was created, and the response body contains the representation</td>\n</tr>\n<tr>\n<td align=\"center\">204</td>\n<td align=\"left\">OK - NO CONTENT</td>\n<td align=\"left\">The request was successful, but no content is returned in the response. In reality this is seldom used for REST APIs and more typically for process APIs. Should include a <code>Location</code> header indicating the location of an associated relevant resource</td>\n</tr>\n<tr>\n<td align=\"center\">207</td>\n<td align=\"left\">MULTI STATUS</td>\n<td align=\"left\">The HTTP 207 Multi-Status response code indicates that there might be a mixture of responses.</td>\n</tr>\n<tr>\n<td align=\"center\">400</td>\n<td align=\"left\">BAD REQUEST</td>\n<td align=\"left\">Missing or bad <code>Security-Context</code> custom header; FHIR request payload does not validate against Implementation Guide</td>\n</tr>\n<tr>\n<td align=\"center\">401</td>\n<td align=\"left\">UNAUTHORIZED</td>\n<td align=\"left\">The supplied credentials, if any, are not sufficient to access the resource</td>\n</tr>\n<tr>\n<td align=\"center\">403</td>\n<td align=\"left\">FORBIDDEN</td>\n<td align=\"left\">Insufficient privilege to access the requested FHIR resource/operation</td>\n</tr>\n<tr>\n<td align=\"center\">404</td>\n<td align=\"left\">NOT FOUND</td>\n<td align=\"left\">The endpoint that the API Consumer is attempting to create or update does not exist. Retrying this request is unlikely to be successful</td>\n</tr>\n<tr>\n<td align=\"center\">405</td>\n<td align=\"left\">METHOD NOT ALLOWED</td>\n<td align=\"left\">You can't POST or PUT to the resource</td>\n</tr>\n<tr>\n<td align=\"center\">422</td>\n<td align=\"left\">UNPROCESSABLE CONTENT</td>\n<td align=\"left\">The server understands the requests content and syntax however it is unable to process the instruction. Retrying this request will not succeed - the request must be modified</td>\n</tr>\n<tr>\n<td align=\"center\">429</td>\n<td align=\"left\">TOO MANY REQUESTS</td>\n<td align=\"left\">Your application is sending too many simultaneous requests</td>\n</tr>\n<tr>\n<td align=\"center\">500</td>\n<td align=\"left\">SERVER ERROR</td>\n<td align=\"left\">We couldn't create or update the resource. Please try again later</td>\n</tr>\n</tbody>\n</table>\n<h4>Delete (DELETE) Operation Statuses</h4>\n<table class=\"grid\">\n<thead>\n<tr>\n<th align=\"center\"><strong>Code</strong></th>\n<th align=\"left\"><strong>Meaning</strong></th>\n<th align=\"left\"><strong>Description</strong></th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td align=\"center\">204</td>\n<td align=\"left\">OK</td>\n<td align=\"left\">The request was successful; the resource was deleted</td>\n</tr>\n<tr>\n<td align=\"center\">400</td>\n<td align=\"left\">BAD REQUEST</td>\n<td align=\"left\">Missing or bad <code>Security-Context</code> custom header; FHIR request payload does not validate against Implementation Guide</td>\n</tr>\n<tr>\n<td align=\"center\">401</td>\n<td align=\"left\">UNAUTHORIZED</td>\n<td align=\"left\">The supplied credentials, if any, are not sufficient to access the resource</td>\n</tr>\n<tr>\n<td align=\"center\">403</td>\n<td align=\"left\">FORBIDDEN</td>\n<td align=\"left\">Insufficient privilege to access the requested FHIR resource/operation</td>\n</tr>\n<tr>\n<td align=\"center\">404</td>\n<td align=\"left\">NOT FOUND</td>\n<td align=\"left\"/>\n</tr>\n<tr>\n<td align=\"center\">405</td>\n<td align=\"left\">METHOD NOT ALLOWED</td>\n<td align=\"left\">You can't DELETE the resource</td>\n</tr>\n<tr>\n<td align=\"center\">429</td>\n<td align=\"left\">TOO MANY REQUESTS</td>\n<td align=\"left\">Your application is sending too many simultaneous requests</td>\n</tr>\n<tr>\n<td align=\"center\">500</td>\n<td align=\"left\">SERVER ERROR</td>\n<td align=\"left\">We couldn't delete the resource. Please try again later</td>\n</tr>\n</tbody>\n</table>\n<h3>Non existent API endpoints</h3>\n<p>When a consumer attempts to call a non-existent API end point, respond\nwith a <strong>501 Not Implemented</strong> status code.</p>\n</div></li></ul></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><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=\"#DocumentReference1-1\">DocumentReference</a></td><td><a href=\"StructureDefinition-nz-screening-summary.html\">https://fhir-ig.digital.health.nz/screening/StructureDefinition/nz-screening-summary</a></td><td class=\"text-center\"></td><td class=\"text-center\">y</td><td class=\"text-center\"></td><td class=\"text-center\"></td><td>subject, category, contenttype, _include</td><td><code>DocumentReference:subject</code></td><td><code>not-supported</code></td><td/></tr></tbody></table></div><hr/><div class=\"panel panel-default\"><div class=\"panel-heading\"><h4 id=\"DocumentReference1-1\" class=\"panel-title\"><span style=\"float: right;\">Resource Conformance: supported </span>DocumentReference</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-nz-screening-summary.html\">ScreeningSummaryDocument</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>search-type</code>.</li></ul></div></div><p/><div class=\"row\"><div class=\"col-12\"><span class=\"lead\">Documentation</span><blockquote><div><p>Provides a document rendition of screening summary information</p>\n</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>subject</td><td><code>reference</code></td><td><div><p>NHI of the person who is the subject of the screening summary document.</p>\n<ul>\n<li>If no screening information exists in the Register for a given subject NHI, the API returns <code>200 OK</code> and an empty FHIR Bundle.</li>\n</ul>\n</div></td></tr><tr><td><b>SHALL</b></td><td>category</td><td><code>token</code></td><td><div><p>Filters screening summaries by selecting the type of screening programme</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td>contenttype</td><td><code>token</code></td><td><div><p>Optional parameter that allows a PDF rendition (#application/pdf) of the screening summary content to be requested instead of the default HTML.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td>_include</td><td><code>token</code></td><td><div><p>The optional parameter _include is used to follow links 'forward'. For example, to include relevant Patient resources for requested Encounter matches, based on the Encounter.subject element, using either the subject or patient search parameters..</p>\n</div></td></tr></tbody></table></div><div class=\"col-lg-5\">\u00a0</div></div></div></div></div></div>"
},
"extension" : [
{
"extension" : [
{
"url" : "licenseURL",
"valueUri" : "https://www.tewhatuora.govt.nz/assets/Our-health-system/Digital-health/Digital-Service-Hub/API-Access-and-Use-Agreement.docx"
},
{
"url" : "externalDocs",
"valueUri" : "https://fhir-ig.digital.health.nz/screening"
},
{
"url" : "licenseName",
"valueString" : "Health New Zealand Digital Services Hub API Access and Use Agreement"
},
{
"extension" : [
{
"extension" : [
{
"url" : "key",
"valueString" : "Correlation-Id"
},
{
"url" : "value",
"valueUri" : "https://raw.githubusercontent.com/tewhatuora/schemas/main/shared-care/Correlation-Id.json"
},
{
"url" : "required",
"valueBoolean" : false
}
],
"url" : "https://fhir-ig.digital.health.nz/hnz-digital-tooling/StructureDefinition/custom-headers-extension"
},
{
"extension" : [
{
"url" : "key",
"valueString" : "x-api-key"
},
{
"url" : "value",
"valueUri" : "https://raw.githubusercontent.com/tewhatuora/schemas/main/shared-care/Api-Key.json"
},
{
"url" : "required",
"valueBoolean" : true
}
],
"url" : "https://fhir-ig.digital.health.nz/hnz-digital-tooling/StructureDefinition/custom-headers-extension"
},
{
"extension" : [
{
"url" : "key",
"valueString" : "Request-Context"
},
{
"url" : "value",
"valueUri" : "https://raw.githubusercontent.com/tewhatuora/schemas/main/openapi-definitions/Request-Context.json"
},
{
"url" : "required",
"valueBoolean" : true
},
{
"url" : "documentation",
"valueString" : "A base64-encoded JSON object that defines the context of the current request.\nSee https://github.com/tewhatuora/schemas/blob/main/json-schema/Request-Context-v2.json for the schema this object must conform to."
}
],
"url" : "https://fhir-ig.digital.health.nz/hnz-digital-tooling/StructureDefinition/custom-headers-extension"
}
],
"url" : "globalHeaders"
}
],
"url" : "https://fhir-ig.digital.health.nz/hnz-digital-tooling/StructureDefinition/resource-metadata-extension"
}
],
"url" : "https://fhir-ig.digital.health.nz/screening/CapabilityStatement/FHIRScreeningCapabilityStatement",
"version" : "1.0.2",
"name" : "FHIRScreeningCapabilityStatement",
"title" : "National Screening FHIR API Capability Statement",
"status" : "draft",
"date" : "2024-05-03",
"publisher" : "Health New Zealand | Te Whatu Ora",
"contact" : [
{
"name" : "Health New Zealand | Te Whatu Ora",
"telecom" : [
{
"system" : "url",
"value" : "https://www.tewhatuora.govt.nz/"
},
{
"system" : "email",
"value" : "integration@tewhatuora.govt.nz"
}
]
},
{
"name" : "HNZ Integration Team",
"telecom" : [
{
"system" : "email",
"value" : "integration@tewhatuora.govt.nz",
"use" : "work"
}
]
}
],
"description" : "National Screening FHIR API",
"jurisdiction" : [
{
"coding" : [
{
"system" : "urn:iso:std:iso:3166",
"code" : "NZ",
"display" : "New Zealand"
}
]
}
],
"kind" : "instance",
"implementation" : {
"description" : "National Screening FHIR API",
"url" : "https://api.nss.digital.health.nz/fhir/R4"
},
"fhirVersion" : "4.0.1",
"format" : [
"json"
],
"rest" : [
{
"mode" : "server",
"security" : {
"extension" : [
{
"extension" : [
{
"url" : "token",
"valueUri" : "https://ppd.auth.services.health.nz/realms/hnz-integration/protocol/openid-connect/token"
}
],
"url" : "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris"
},
{
"url" : "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode" : "client-confidential-symmetric"
}
],
"cors" : true,
"service" : [
{
"coding" : [
{
"code" : "SMART-on-FHIR"
}
]
}
]
},
"resource" : [
{
"type" : "DocumentReference",
"profile" : "https://fhir-ig.digital.health.nz/screening/StructureDefinition/nz-screening-summary",
"documentation" : "Provides a document rendition of screening summary information",
"interaction" : [
{
"code" : "search-type"
}
],
"versioning" : "versioned",
"readHistory" : false,
"updateCreate" : false,
"conditionalCreate" : false,
"conditionalRead" : "not-supported",
"conditionalUpdate" : false,
"conditionalDelete" : "not-supported",
"searchInclude" : [
"DocumentReference:subject"
],
"searchRevInclude" : [
"not-supported"
],
"searchParam" : [
{
"name" : "subject",
"definition" : "https://hl7.org/fhir/searchparameter-registry.html#DocumentReference-subject",
"type" : "reference",
"documentation" : "NHI of the person who is the subject of the screening summary document.\n- If no screening information exists in the Register for a given subject NHI, the API returns `200 OK` and an empty FHIR Bundle."
},
{
"name" : "category",
"definition" : "https://hl7.org/fhir/searchparameter-registry.html#DocumentReference-category",
"type" : "token",
"documentation" : "Filters screening summaries by selecting the type of screening programme"
},
{
"name" : "contenttype",
"definition" : "https://hl7.org/fhir/searchparameter-registry.html#DocumentReference-contenttype",
"type" : "token",
"documentation" : "Optional parameter that allows a PDF rendition (#application/pdf) of the screening summary content to be requested instead of the default HTML."
},
{
"name" : "_include",
"definition" : "https://www.hl7.org/implement/standards/FHIR/search.html#_include",
"type" : "token",
"documentation" : "The optional parameter _include is used to follow links 'forward'. For example, to include relevant Patient resources for requested Encounter matches, based on the Encounter.subject element, using either the subject or patient search parameters.."
}
]
}
],
"interaction" : [
{
"code" : "search-system",
"documentation" : "### Request-Context custom header\n\nAll screening FHIR API requests must include the HNZ request context *custom header* supplying identifiers for the health user \nand organisation behind the API request.\n\nThis context is supplied using the 'Request-Context' custom header in the form of a base64-encoded JSON object.\n\n|**Context property**|**Value**|\n|:------------------|:---------|\n| `userIdentifier` | The userid of the user as authenticated by the PMS/health application (REQUIRED) |\n| `purposeOfUse` | Set to `\"SCREENING\"` (REQUIRED) |\n| `userFullName` | Full name of the user of the PMS/health application. (REQUIRED) |\n| `hpiPractitioner` | The Common Person Number (aka HPI Practitioner identifier) of the practitioner using the application (REQUIRED) |\n| `hpiOrganisation` or `hpiFacility` | HPI identifier for the organisation or facility where the user is located -- at least one is REQUIRED |\n\nA schema definition and examples for `Request-Context` can be [found here](https://github.com/tewhatuora/schemas/blob/main/json-schema/Request-Context-v2.json)\n\n### Error status codes\n\n#### Read (GET) Operation Statuses\n\n|**Code**|**Meaning**|**Description**|\n|:--:|:-----------------|:--|\n|200|OK |The request was successful, and the response body contains the representation requested|\n|302|FOUND |A common redirect response; you can GET the representation at the URI in the Location response header|\n|304|NOT MODIFIED |Your client's cached version of the representation is still up to date|\n|400|BAD REQUEST |Missing or bad `Security-Context` custom header; FHIR request payload does not validate against Implementation Guide|\n|401|UNAUTHORIZED |The supplied credentials, if any, are not sufficient to access the resource|\n|403|FORBIDDEN |Insufficient privilege to access the requested FHIR resource/operation|\n|404|NOT FOUND |The requested representation was not found. Retrying this request is unlikely to be successful|\n|429|TOO MANY REQUESTS |Your application is sending too many simultaneous requests|\n|500|SERVER ERROR |An internal server error prevented return of the representation response|\n|503|SERVICE UNAVAILABLE|We are temporarily unable to return the representation. Please wait and try again later|\n\n#### Search (GET) Operation Statuses\n\n|**Code**|**Meaning** |**OperationOutcome** in response?|**Description**|\n|:--:|:-----------------|:----------------------------------|:----------------------------------|\n|200|OK |Yes, when there are additional messages about a match result|The request was successful, and the response body contains the representation requested|\n|302|FOUND |No |A common redirect response; you can GET the representation at the URI in the Location response header|\n|400|BAD REQUEST |Missing or bad `Security-Context` custom header; FHIR request payload does not validate against Implementation Guide|\n|401|UNAUTHORIZED |The supplied credentials, if any, are not sufficient to access the resource|\n|403|FORBIDDEN |Insufficient privilege to access the requested FHIR resource/operation|\n|429|TOO MANY REQUESTS |No |Your application is sending too many simultaneous requests|\n|500|SERVER ERROR |No |An internal server error prevented return of the representation response|\n|503|SERVICE UNAVAILABLE|No |The server is temporarily unable to return the representation. Please wait and try again later|\n\n#### Create (POST or PUT) Operation Statuses\n\n|**Code**|**Meaning**|**Description**|\n|:--:|:-----------------|:--|\n|200|OK |The request was successful, and the resource was updated. The response body contains the updated representation|\n|201|CREATED |The request was successful, a new resource was created, and the response body contains the representation|\n|204|OK - NO CONTENT |The request was successful, but no content is returned in the response. In reality this is seldom used for REST APIs and more typically for process APIs. Should include a `Location` header indicating the location of an associated relevant resource|\n|207|MULTI STATUS |The HTTP 207 Multi-Status response code indicates that there might be a mixture of responses.|\n|400|BAD REQUEST |Missing or bad `Security-Context` custom header; FHIR request payload does not validate against Implementation Guide|\n|401|UNAUTHORIZED |The supplied credentials, if any, are not sufficient to access the resource|\n|403|FORBIDDEN |Insufficient privilege to access the requested FHIR resource/operation|\n|404|NOT FOUND |The endpoint that the API Consumer is attempting to create or update does not exist. Retrying this request is unlikely to be successful|\n|405|METHOD NOT ALLOWED |You can't POST or PUT to the resource|\n|422|UNPROCESSABLE CONTENT|The server understands the requests content and syntax however it is unable to process the instruction. Retrying this request will not succeed - the request must be modified|\n|429|TOO MANY REQUESTS |Your application is sending too many simultaneous requests|\n|500|SERVER ERROR |We couldn't create or update the resource. Please try again later|\n\n#### Delete (DELETE) Operation Statuses\n\n|**Code**|**Meaning**|**Description**|\n|:--:|:-----------------|:--|\n|204|OK |The request was successful; the resource was deleted|\n|400|BAD REQUEST |Missing or bad `Security-Context` custom header; FHIR request payload does not validate against Implementation Guide|\n|401|UNAUTHORIZED |The supplied credentials, if any, are not sufficient to access the resource|\n|403|FORBIDDEN |Insufficient privilege to access the requested FHIR resource/operation|\n|404|NOT FOUND | |\n|405|METHOD NOT ALLOWED |You can't DELETE the resource|\n|429|TOO MANY REQUESTS |Your application is sending too many simultaneous requests|\n|500|SERVER ERROR |We couldn't delete the resource. Please try again later|\n\n### Non existent API endpoints\n\nWhen a consumer attempts to call a non-existent API end point, respond\nwith a **501 Not Implemented** status code."
}
]
}
]
}