HSAAP Special Authority FHIR Implementation Guide
0.1.1 - draft
HSAAP Special Authority FHIR Implementation Guide
0.1.1 - draft
HSAAP Special Authority FHIR Implementation Guide - Local Development build (v0.1.1) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| Draft as of 2026-10-15 |
{
"resourceType" : "CapabilityStatement",
"id" : "SpecialAuthorityFHIRAPICapabilityStatement",
"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 SpecialAuthorityFHIRAPICapabilityStatement</b></p><a name=\"SpecialAuthorityFHIRAPICapabilityStatement\"> </a><a name=\"hcSpecialAuthorityFHIRAPICapabilityStatement\"> </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\">Special Authority FHIR Server Capability Statement</h2><ul><li>Implementation Guide Version: 0.1.1 </li><li>FHIR Version: 4.0.1 </li><li>Supported Formats: <code>application/fhir+json</code></li><li>Published on: 2026-10-15 </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><p>All token searches on identifiers SHALL be system-qualified (system|value). All requests require a validated access token and a validated signed Request-Context header.</p>\n</div><div class=\"lead\"><em>Security</em></div><div class=\"row\"><div class=\"col-lg-6\">Enable CORS: no</div><div class=\"col-lg-6\">Security services supported: <code>SMART-on-FHIR</code></div></div><blockquote><div><p>OAuth 2.0 client credentials flow and signed Request-Context header, per the Health NZ Digital Services Hub onboarding process. The authenticated requester identity is never taken from the FHIR payload.</p>\n</div></blockquote></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=\"#Claim1-1\">Claim</a></td><td><a href=\"StructureDefinition-sa-claim.html\">https://fhir-ig.digital.health.nz/special-authority/StructureDefinition/sa-claim</a><br/><em>Additional supported profiles:</em><br/>\u00a0\u00a0<a href=\"StructureDefinition-sa-claim.html\">SA Claim</a></td><td class=\"text-center\"/><td class=\"text-center\">y</td><td class=\"text-center\"/><td class=\"text-center\"/><td>identifier, patient, requestor, application-status, created</td><td><code>Claim:patient</code>, <code>Claim:requestor</code>, <code>Claim:supportinginfo</code></td><td/><td><code>$submit</code></td></tr><tr><td><a href=\"#ClaimResponse1-2\">ClaimResponse</a></td><td>Supported Profiles<br/>\u00a0\u00a0<a href=\"StructureDefinition-sa-application-claimresponse.html\">SA Application ClaimResponse</a><br/>\u00a0\u00a0<a href=\"StructureDefinition-sa-approval-claimresponse.html\">SA Approval ClaimResponse</a></td><td class=\"text-center\"/><td class=\"text-center\">y</td><td class=\"text-center\"/><td class=\"text-center\"/><td>identifier, request, patient, requestor, approval-status, approval-valid-on, approval-expiring, approval-provider-id, approval-version-state, _elements</td><td><code>ClaimResponse:request</code></td><td/><td/></tr></tbody></table></div><hr/><div class=\"panel panel-default\"><div class=\"panel-heading\"><h4 id=\"Claim1-1\" class=\"panel-title\"><span style=\"float: right;\">Resource Conformance: unspecified </span>Claim</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-sa-claim.html\">SA Claim</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-sa-claim.html\">SA Claim</a></p></div><div class=\"col-lg-6\"><span class=\"lead\">Interaction summary</span><br/><ul><li>Supports <br/><code>search-type</code><div><p>Search Applications, or retrieve a submitted Application by Application Number with _include. Search results are summary representations: referenced resources are only resolved via _include.</p>\n</div></li></ul></div></div><p/><div class=\"row\"><div class=\"col-12\"><span class=\"lead\">Documentation</span><blockquote><div><p>Special Authority Applications. Submitted with $submit; enquired with search.</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><a href=\"http://hl7.org/fhir/R4/claim.html#search\">identifier</a></td><td><code>token</code></td><td><div><p>Application Number. SHALL be system-qualified.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"http://hl7.org/fhir/R4/claim.html#search\">patient</a></td><td><code>reference</code></td><td><div><p>Supports the chained form patient.identifier=nhi-system|NHI only.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"SearchParameter-claim-requestor.html\">requestor</a></td><td><code>reference</code></td><td><div><p>Supports requestor:Practitioner.identifier with the HPI CPN system or an NZ registration authority system.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"SearchParameter-application-status.html\">application-status</a></td><td><code>token</code></td><td><div><p>SUBMITTED | PENDING_REVIEW | CANCELLED | DONE</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"http://hl7.org/fhir/R4/claim.html#search\">created</a></td><td><code>date</code></td><td><div><p>Submission date range: ge and le map to submittedFrom and submittedTo.</p>\n</div></td></tr></tbody></table></div><div class=\"col-lg-5\">\u00a0</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-sa-claim-submit.html\">$submit</a></td><td><div/></td></tr></tbody></table></div></div></div></div></div><div class=\"panel panel-default\"><div class=\"panel-heading\"><h4 id=\"ClaimResponse1-2\" class=\"panel-title\"><span style=\"float: right;\">Resource Conformance: unspecified </span>ClaimResponse</h4></div><div class=\"panel-body\"><div class=\"container\"><div class=\"row\"><div class=\"col-lg-4\"><span class=\"lead\">Core FHIR Resource</span><br/><a href=\"http://hl7.org/fhir/R4/claimresponse.html\">ClaimResponse</a></div><div class=\"col-lg-4\"><span class=\"lead\">Reference Policy</span><br/></div><div class=\"col-lg-4\"><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-6\"><span class=\"lead\">Supported Profiles</span><p><a href=\"StructureDefinition-sa-application-claimresponse.html\">SA Application ClaimResponse</a><br/><a href=\"StructureDefinition-sa-approval-claimresponse.html\">SA Approval ClaimResponse</a></p></div></div><p/><div class=\"row\"><div class=\"col-12\"><span class=\"lead\">Documentation</span><blockquote><div><p>Application outcomes (searched by request.identifier) and Approvals (searched by Approval Number, NHI or practitioner). An Approval search SHALL supply at least one of identifier, patient.identifier or requestor:Practitioner.identifier. approval-valid-on and approval-expiring are mutually exclusive.</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><a href=\"http://hl7.org/fhir/R4/claimresponse.html#search\">identifier</a></td><td><code>token</code></td><td><div><p>Approval Number. SHALL be system-qualified.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"http://hl7.org/fhir/R4/claimresponse.html#search\">request</a></td><td><code>reference</code></td><td><div><p>Supports the chained form request.identifier=application-number-system|applicationNumber.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"http://hl7.org/fhir/R4/claimresponse.html#search\">patient</a></td><td><code>reference</code></td><td><div><p>Supports the chained form patient.identifier=nhi-system|NHI only.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"http://hl7.org/fhir/R4/claimresponse.html#search\">requestor</a></td><td><code>reference</code></td><td><div><p>Supports requestor:Practitioner.identifier with the HPI CPN system or an NZ registration authority system.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"SearchParameter-approval-status.html\">approval-status</a></td><td><code>token</code></td><td><div><p>ACTIVE | CANCELLED | REVOKED</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"SearchParameter-approval-valid-on.html\">approval-valid-on</a></td><td><code>date</code></td><td><div><p>Approvals valid on the supplied date.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"SearchParameter-approval-expiring.html\">approval-expiring</a></td><td><code>date</code></td><td><div><p>Approvals expiring within a date range.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"SearchParameter-approval-provider-id.html\">approval-provider-id</a></td><td><code>token</code></td><td><div><p>Provider - pharmacy - on the Approval. SHALL be system-qualified.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"SearchParameter-approval-version-state.html\">approval-version-state</a></td><td><code>token</code></td><td><div><p>LATEST - default - or PREVIOUS or ALL.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td>_elements</td><td><code>special</code></td><td><div><p>Supported for Retrieve Application Outcome: _elements=extension,preAuthRef.</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/special-authority"
},
{
"url" : "licenseName",
"valueString" : "Health New Zealand Digital Services Hub API Access and Use Agreement"
},
{
"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" : "Signed Request-Context header asserting the authenticated user, organisation and facility. Validated on every request."
}
],
"url" : "https://fhir-ig.digital.health.nz/hnz-digital-tooling/StructureDefinition/custom-headers-extension"
},
{
"extension" : [
{
"url" : "key",
"valueString" : "X-Correlation-Id"
},
{
"url" : "value",
"valueUri" : "https://raw.githubusercontent.com/tewhatuora/schemas/main/shared-care/Correlation-Id.json"
},
{
"url" : "required",
"valueBoolean" : false
},
{
"url" : "documentation",
"valueString" : "Optional client-supplied correlation id, returned in the response and recorded in audit events."
}
],
"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/special-authority/CapabilityStatement/SpecialAuthorityFHIRAPICapabilityStatement",
"version" : "0.1.1",
"name" : "SpecialAuthorityFHIRAPICapabilityStatement",
"title" : "Special Authority FHIR Server Capability Statement",
"status" : "draft",
"experimental" : false,
"date" : "2026-10-15",
"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" : "Health NZ | Te Whatu Ora Special Authority FHIR API",
"jurisdiction" : [
{
"coding" : [
{
"system" : "urn:iso:std:iso:3166",
"code" : "NZ",
"display" : "New Zealand"
}
]
}
],
"kind" : "instance",
"implementation" : {
"description" : "Production Special Authority FHIR API",
"url" : "https://api.sa.digital.health.nz/s2s/fhir/R4"
},
"fhirVersion" : "4.0.1",
"format" : [
"application/fhir+json"
],
"rest" : [
{
"mode" : "server",
"documentation" : "All token searches on identifiers SHALL be system-qualified (system|value). All requests require a validated access token and a validated signed Request-Context header.",
"security" : {
"extension" : [
{
"extension" : [
{
"url" : "token",
"valueUri" : "https://auth.services.health.nz/realms/hnz-integration/protocol/openid-connect/token"
},
{
"url" : "authorize",
"valueUri" : "https://auth.services.health.nz/realms/hnz-integration/protocol/openid-connect/auth"
}
],
"url" : "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris"
},
{
"url" : "http://fhir-registry.smarthealthit.org/StructureDefinition/capabilities",
"valueCode" : "client-confidential-symmetric"
}
],
"cors" : false,
"service" : [
{
"coding" : [
{
"system" : "http://terminology.hl7.org/CodeSystem/restful-security-service",
"code" : "SMART-on-FHIR"
}
]
}
],
"description" : "OAuth 2.0 client credentials flow and signed Request-Context header, per the Health NZ Digital Services Hub onboarding process. The authenticated requester identity is never taken from the FHIR payload."
},
"resource" : [
{
"type" : "Claim",
"profile" : "https://fhir-ig.digital.health.nz/special-authority/StructureDefinition/sa-claim",
"supportedProfile" : [
🔗 "https://fhir-ig.digital.health.nz/special-authority/StructureDefinition/sa-claim"
],
"documentation" : "Special Authority Applications. Submitted with $submit; enquired with search.",
"interaction" : [
{
"code" : "search-type",
"documentation" : "Search Applications, or retrieve a submitted Application by Application Number with _include. Search results are summary representations: referenced resources are only resolved via _include."
}
],
"searchInclude" : [
"Claim:patient",
"Claim:requestor",
"Claim:supportinginfo"
],
"searchParam" : [
{
"name" : "identifier",
"definition" : "http://hl7.org/fhir/SearchParameter/Claim-identifier",
"type" : "token",
"documentation" : "Application Number. SHALL be system-qualified."
},
{
"name" : "patient",
"definition" : "http://hl7.org/fhir/SearchParameter/Claim-patient",
"type" : "reference",
"documentation" : "Supports the chained form patient.identifier=nhi-system|NHI only."
},
{
"name" : "requestor",
"definition" : "https://fhir-ig.digital.health.nz/special-authority/SearchParameter/claim-requestor",
"type" : "reference",
"documentation" : "Supports requestor:Practitioner.identifier with the HPI CPN system or an NZ registration authority system."
},
{
"name" : "application-status",
"definition" : "https://fhir-ig.digital.health.nz/special-authority/SearchParameter/application-status",
"type" : "token",
"documentation" : "SUBMITTED | PENDING_REVIEW | CANCELLED | DONE"
},
{
"name" : "created",
"definition" : "http://hl7.org/fhir/SearchParameter/Claim-created",
"type" : "date",
"documentation" : "Submission date range: ge and le map to submittedFrom and submittedTo."
}
],
"operation" : [
{
"name" : "submit",
"definition" : "https://fhir-ig.digital.health.nz/special-authority/OperationDefinition/sa-claim-submit"
}
]
},
{
"type" : "ClaimResponse",
"supportedProfile" : [
🔗 "https://fhir-ig.digital.health.nz/special-authority/StructureDefinition/sa-application-claimresponse"🔗 ,
"https://fhir-ig.digital.health.nz/special-authority/StructureDefinition/sa-approval-claimresponse"
],
"documentation" : "Application outcomes (searched by request.identifier) and Approvals (searched by Approval Number, NHI or practitioner). An Approval search SHALL supply at least one of identifier, patient.identifier or requestor:Practitioner.identifier. approval-valid-on and approval-expiring are mutually exclusive.",
"interaction" : [
{
"code" : "search-type"
}
],
"searchInclude" : [
"ClaimResponse:request"
],
"searchParam" : [
{
"name" : "identifier",
"definition" : "http://hl7.org/fhir/SearchParameter/ClaimResponse-identifier",
"type" : "token",
"documentation" : "Approval Number. SHALL be system-qualified."
},
{
"name" : "request",
"definition" : "http://hl7.org/fhir/SearchParameter/ClaimResponse-request",
"type" : "reference",
"documentation" : "Supports the chained form request.identifier=application-number-system|applicationNumber."
},
{
"name" : "patient",
"definition" : "http://hl7.org/fhir/SearchParameter/ClaimResponse-patient",
"type" : "reference",
"documentation" : "Supports the chained form patient.identifier=nhi-system|NHI only."
},
{
"name" : "requestor",
"definition" : "http://hl7.org/fhir/SearchParameter/ClaimResponse-requestor",
"type" : "reference",
"documentation" : "Supports requestor:Practitioner.identifier with the HPI CPN system or an NZ registration authority system."
},
{
"name" : "approval-status",
"definition" : "https://fhir-ig.digital.health.nz/special-authority/SearchParameter/approval-status",
"type" : "token",
"documentation" : "ACTIVE | CANCELLED | REVOKED"
},
{
"name" : "approval-valid-on",
"definition" : "https://fhir-ig.digital.health.nz/special-authority/SearchParameter/approval-valid-on",
"type" : "date",
"documentation" : "Approvals valid on the supplied date."
},
{
"name" : "approval-expiring",
"definition" : "https://fhir-ig.digital.health.nz/special-authority/SearchParameter/approval-expiring",
"type" : "date",
"documentation" : "Approvals expiring within a date range."
},
{
"name" : "approval-provider-id",
"definition" : "https://fhir-ig.digital.health.nz/special-authority/SearchParameter/approval-provider-id",
"type" : "token",
"documentation" : "Provider - pharmacy - on the Approval. SHALL be system-qualified."
},
{
"name" : "approval-version-state",
"definition" : "https://fhir-ig.digital.health.nz/special-authority/SearchParameter/approval-version-state",
"type" : "token",
"documentation" : "LATEST - default - or PREVIOUS or ALL."
},
{
"name" : "_elements",
"type" : "special",
"documentation" : "Supported for Retrieve Application Outcome: _elements=extension,preAuthRef."
}
]
}
]
}
]
}