HSAAP Special Authority FHIR Implementation Guide
0.1.1 - draft New Zealand flag

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

Enquire Approval

An Approval is enquired independently of the Application that created it; no Application Number needs to be known. Approvals are returned as SA Approval ClaimResponse resources.

How an Approval is represented

FHIR element Meaning
identifier, preAuthRef Approval Number (same value in both)
preAuthPeriod.start / .end Effective and expiry dates. A lifetime Approval has a far-future expiry date; there is no sentinel value.
patient The patient (resolved from the NHI)
requestor The prescribing Practitioner who authored the originating Application
request The originating Application, where still retrievable
meta.lastUpdated When this Approval version was created
approval-detail Approval type, status (ACTIVE / CANCELLED / REVOKED), form number and version, provider (pharmacy)
approval-coverage Coverage - only for NPPA and panel Approvals
status, outcome Always active and complete. Mandatory in FHIR R4; carry no HSAAP meaning.

Status. ClaimResponse.status is bound to the financial resource status value set and cannot express the Approval Store's ACTIVE, CANCELLED or REVOKED. Read the Approval status from approval-detail.status.

Coverage. A standard CHEM/RISK Approval's coverage is derivable from approval-detail.formNumber and formVersion against the schedule, so it is not returned. NPPA and panel Approvals have no schedule form, so their coverage is carried explicitly (D15).

Freshness. The ClaimResponse is built from the current Approval Store record on every enquiry. It is not a replay of the ClaimResponse returned at submission, because cancellation, revocation and update all create new Approval versions.

Examples: CHEM Approval, NPPA Approval with coverage and provider.

Retrieve an Approval

GET [base]/ClaimResponse?identifier=https://fhir-ig.digital.health.nz/special-authority/ns/approval-number|{approvalNumber}

Search Approvals

Filter FHIR parameter Example
NHI patient.identifier patient.identifier=https://standards.digital.health.nz/ns/nhi-id\|ZZZ0016
Prescriber by CPN requestor:Practitioner.identifier requestor:Practitioner.identifier=https://standards.digital.health.nz/ns/hpi-person-id\|99ZZZZ
Prescriber by registration requestor:Practitioner.identifier requestor:Practitioner.identifier=https://standards.digital.health.nz/ns/medical-council-id\|12345
Approval status approval-status approval-status=ACTIVE
Valid on date approval-valid-on approval-valid-on=2026-09-18
Expiring between approval-expiring approval-expiring=ge2026-10-01&approval-expiring=le2026-12-31
Provider (pharmacy) approval-provider-id approval-provider-id=https://fhir-ig.digital.health.nz/special-authority/ns/pharmacy-claimant-number\|1234
Version state approval-version-state approval-version-state=ALL

Rules:

  • A search SHALL supply at least one of the Approval Number (identifier), the NHI, or a practitioner identifier. The other filters narrow a result set rather than define one. A search supplying none of these is rejected.
  • approval-valid-on and approval-expiring are mutually exclusive. Supplying both is rejected.
  • approval-valid-on matches Approvals whose preAuthPeriod contains the date. This is not standard FHIR date search on a Period, which is why it is a custom parameter.
  • A registration search is a query-time input only. Approvals are stored against the practitioner's CPN, so the service resolves the registration to a CPN first. If it does not resolve, an empty result set is returned.

Approval versions

Approval versions are not FHIR resource versions (D17). meta.versionId is not populated and vread / _history are not supported. By default only the latest version of each Approval is returned. With approval-version-state=ALL, each version is returned as a distinct ClaimResponse sharing the same Approval Number, ordered by meta.lastUpdated. PREVIOUS returns superseded versions only. A specific historical version cannot be retrieved directly.

Example: all versions of an Approval for a patient.

Worked examples

Purpose FHIR request
All (current and historical) Approvals for a patient GET [base]/ClaimResponse?patient.identifier={nhi-system}\|{nhi}&approval-version-state=ALL
Current Approvals for a patient valid today GET [base]/ClaimResponse?patient.identifier={nhi-system}\|{nhi}&approval-valid-on=2026-10-15
Current Approvals for a pharmacy GET [base]/ClaimResponse?approval-provider-id={claimant-number-system}\|{providerId}
Current Approvals by prescriber GET [base]/ClaimResponse?requestor:Practitioner.identifier={hpi-cpn-system}\|{cpn}
All Approvals by prescriber GET [base]/ClaimResponse?requestor:Practitioner.identifier={hpi-cpn-system}\|{cpn}&approval-version-state=ALL
Active Approvals expiring this quarter, by registration GET [base]/ClaimResponse?requestor:Practitioner.identifier={registration-system}\|{number}&approval-expiring=ge2026-10-01&approval-expiring=le2026-12-31&approval-status=ACTIVE