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
| Official URL: https://fhir-ig.digital.health.nz/special-authority/ImplementationGuide/tewhatuora.specialauthority | Version: 0.1.1 | |||
| Draft as of 2026-10-16 | Computable Name: HSAAP Special Authority FHIR Implementation Guide | |||
This Implementation Guide defines the HSAAP Special Authority sector facing FHIR API. It allows Practice Management Systems (PMS), the SOAP to FHIR Broker, the Special Authority application in the Population Health Salesforce org, and any future FHIR-native sector client to:
The API is hosted in MuleSoft, which validates each request against the profiles in this guide, translates it to the RESTful API of the special-authority-application-service, and translates the response back into FHIR. The special-authority-application-service neither produces nor consumes FHIR.
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 HSAAP 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: business rule content and rule evaluation sequence (Application Decisioning design); HL7 v2 to FHIR translation (SOAP to FHIR Broker); decisioning; the Application Store, Approval/Entitlement Store and Pharmaceutical Schedule internal APIs; and authentication and authorisation mechanics (Security design), which are summarised on Security, Onboarding and Auditing.
| IG | Package | FHIR | Comment |
|---|---|---|---|
  HSAAP Special Authority FHIR Implementation Guide | tewhatuora.specialauthority#0.1.1 | 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.