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
The API validates only what it can determine without schedule or clinical knowledge. Everything requiring the form definition, patient or practitioner resolution, or prior approval state is assessed by the Special Authority service. This guarantees every channel receives the same outcome for equivalent Applications.
| Performed by the API | Performed by the service |
|---|---|
| Token validity, scopes and client identity | Form number and version resolve to a form in the Pharmaceutical Schedule |
| Well formed FHIR and conformance to the SA profiles | Every criterionIdentifier exists in that exact form version, with no duplicates |
| Presence of the QuestionnaireResponse and mandatory referenced resources | Answer datatypes match the criterion types in the form |
| Form canonical present, well formed and version-pinned | NHI is well formed and resolves |
| Answer datatypes are boolean or string | Practitioner registration is valid and in scope of practice |
| Payload CPN, where present, agrees with the token | Prior approval state, eligibility and clinical criteria |
| Asserted submission context does not conflict with authenticated context | Application Number allocation and check digit |
The service does not check that a minimum number of criteria have been answered. An incomplete Application is valid against these profiles and is declined on assessment.
A request rejected by the API before reaching the service (authentication failure, profile non-conformance, malformed
canonical, conflicting context) is returned with an HTTP 4xx status and an OperationOutcome, which may carry several
issues. No Application is created.
The service assesses fail fast: it stops at the first rule that fails and returns a single outcome. An Application failing several checks surfaces them one submission at a time; the prescriber corrects and resubmits until the Application is approved or declined on a substantive ground.
| Service value | FHIR element |
|---|---|
| Application Number | ClaimResponse.request.identifier |
| Status: SUBMITTED, PENDING_REVIEW, CANCELLED, DONE | application-status.status |
| Outcome: APPROVED, INVALID, DECLINED (DONE only) | application-status.outcome |
| Machine readable reason | application-status.outcomeCode, ClaimResponse.error.code, OperationOutcome.issue.details.coding |
| Human readable reason | application-status.outcomeReason, ClaimResponse.disposition, OperationOutcome.issue.diagnostics |
| Approval Number (approved only) | ClaimResponse.identifier, ClaimResponse.preAuthRef |
| Approval dates (approved only) | ClaimResponse.preAuthPeriod |
Conflicting Approval (declined only, $submit only) |
existing-approval |
The Application status is never mapped to QuestionnaireResponse.status, which cannot distinguish PENDING_REVIEW from DONE.
ClaimResponse.outcome is mandatory in FHIR R4. It is populated as follows, but application-status is authoritative:
| Application status / outcome | ClaimResponse.outcome |
|---|---|
| SUBMITTED, PENDING_REVIEW | queued |
| DONE / APPROVED, DONE / DECLINED | complete |
| DONE / INVALID | error |
| CANCELLED | complete |
Outcome codes, their conditions and rule evaluation order are defined by Health NZ. A single Error Code Catalogue is published and used for every channel, so the reason text is identical everywhere.
The catalogue is represented by the SA Outcome Code code system, which is defined with
content = not-present until the catalogue is published.