Special Authority FHIR Implementation Guide
0.1.2 - draft
Special Authority FHIR Implementation Guide
0.1.2 - draft
Special Authority FHIR Implementation Guide - Local Development build (v0.1.2) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| Official URL: https://fhir-ig.digital.health.nz/special-authority/ImplementationGuide/tewhatuora.specialauthority | Version: 0.1.2 | |||
| Draft as of 2026-10-21 | Computable Name: Special Authority FHIR Implementation Guide | |||
This Implementation Guide defines the Special Authority FHIR API provided by Health New Zealand | Te Whatu Ora. It allows Practice Management Systems (PMS) and other sector clients to:
The API validates each request against the profiles in this guide and returns its responses as FHIR resources.
A Special Authority Application is, in FHIR's own terms, a request for authorisation of funded goods in advance of their
supply, and is therefore modelled as a Claim with use = preauthorization. The clinical criteria and their answers are
carried as a QuestionnaireResponse, not as an encoded string. The outcome, and any resulting Approval, is a
ClaimResponse: preAuthRef and preAuthPeriod carry the Approval Number and its effective and expiry dates.
Da Vinci Prior Authorization Support is used as a pattern reference only. Its US-specific terminology bindings and X12 assumptions are not adopted.
| Resource | Profile | Derived from | Role |
|---|---|---|---|
| Bundle | SA Submission Bundle | Bundle | Request body of Claim/$submit |
| Claim | SA Claim | Claim | The Application |
| QuestionnaireResponse | SA QuestionnaireResponse | QuestionnaireResponse | Clinical criteria and answers |
| Questionnaire | SA Questionnaire | Questionnaire | Constraints on the form canonical (not published in Phase 1) |
| Patient | SA Patient | NZ Base NzPatient |
The patient (NHI) |
| Practitioner | SA Practitioner | NZ Base NzPractitioner |
Applicant and Referrer |
| Organization | SA Organization | NZ Base NzOrganization |
Submitting practice or facility |
| Bundle | SA Response Bundle | Bundle | Response from Claim/$submit |
| ClaimResponse | SA Application ClaimResponse | ClaimResponse | Application status and outcome |
| ClaimResponse | SA Approval ClaimResponse | ClaimResponse | An Approval |
| OperationOutcome | SA Outcome OperationOutcome | OperationOutcome | The single business outcome |
Monetary amounts are never present on a Special Authority Application or Approval. The financial elements of Claim
and ClaimResponse are constrained out rather than left unused and optional.
| Interaction | Request |
|---|---|
| Submit Application | POST [base]/Claim/$submit |
| Retrieve a submitted Application | GET [base]/Claim?identifier=...&_include=... |
| Retrieve Application Outcome | GET [base]/ClaimResponse?request.identifier=... |
| Search Applications | GET [base]/Claim?... |
| Retrieve / Search Approvals | GET [base]/ClaimResponse?... |
The full API is described by the Special Authority FHIR API CapabilityStatement.
In scope: the FHIR profiles, extensions, search parameters and operation used by the sector facing API; the rules a submitter must follow; and how outcomes are rendered.
Out of scope: the content and evaluation order of Special Authority business rules; clinical decisioning; and the detailed mechanics of authentication and authorisation, which are summarised on Security, Onboarding and Auditing.
| IG | Package | FHIR | Comment |
|---|---|---|---|
  Special Authority FHIR Implementation Guide | tewhatuora.specialauthority#0.1.2 | R4 | |
 HL7 Terminology (THO) | hl7.terminology.r4#7.4.0 | R4 | Automatically added as a dependency - all IGs depend on HL7 Terminology |
| FHIR Extensions Pack | hl7.fhir.uv.extensions.r4#5.3.0 | R4 | Automatically added as a dependency - all IGs depend on the HL7 Extension Pack |
 HL7® FHIR® New Zealand Base Implementation Guide | fhir.org.nz.ig.base#3.1.0 | R4 | |
  HL7 Terminology (THO) | hl7.terminology.r4#7.2.0 | R4 | |
| Digital Tooling Implementation Guide | tewhatuora.digitaltooling#0.0.11 | R4 | |
| FHIR Extensions Pack | hl7.fhir.uv.extensions.r4#5.1.0 | R4 | |
| HL7 Terminology (THO) | hl7.terminology.r4#5.5.0 | R4 | |
 FHIR Tooling Extensions IG | hl7.fhir.uv.tools.r4#1.3.0 | R4 | for example references |
Package hl7.fhir.uv.extensions.r4#5.3.0 This IG defines the global extensions - the ones defined for everyone. These extensions are always in scope wherever FHIR is being used (built Sat, May 16, 2026 18:32+1000+10:00) |
Package fhir.org.nz.ig.base#3.1.0 New Zealand base profiles (built Fri, Jul 24, 2026 15:52+1200+12:00) |
Package hl7.fhir.uv.extensions.r4#5.1.0 This IG defines the global extensions - the ones defined for everyone. These extensions are always in scope wherever FHIR is being used (built Sat, Apr 27, 2024 18:39+1000+10:00) |
Package tewhatuora.digitaltooling#0.0.11 FHIR profiles used in FHIR Publishing processes within Health New Zealand Te Whatu Ora (built Wed, Aug 28, 2024 21:00+0000+00:00) |
Package hl7.fhir.uv.tools.r4#1.3.0 This IG defines the extensions that the tools use internally. Some of these extensions are content that are being evaluated for elevation into the main spec, and others are tooling concerns (built Tue, Oct 6, 2026 15:55+1100+11:00) |
This publication includes IP covered under the following statements.