A Special Authority Application: a request for authorisation of funded pharmaceuticals in advance of their supply, i.e. a Claim with use = preauthorization. Submitted inside an SA Submission Bundle to Claim/$submit.

• The clinical criteria and answers are carried by the QuestionnaireResponse referenced from supportingInfo.
• provider references the Applicant - the same Practitioner as QuestionnaireResponse.author. FHIR R4 Claim has no requestor element; the custom requestor search parameter evaluates Claim.provider, so requestor:Practitioner.identifier searches and _include=Claim:requestor resolve to the Applicant.
• identifier carries the Application Number only (D23). It is absent on submission and is populated by the API.
• item is used only for NPPA and panel approval Applications, where no form declares coverage. Standard Special Authority Applications SHALL NOT supply item; coverage is derived from the resolved form at decision time (D6).
• Financial elements are constrained out. Monetary amounts are never present.
• insurance is mandatory in FHIR R4 Claim. It carries a logical reference to the Pharmaceutical Schedule and has no other meaning (see Design Notes).

The submitting practice or facility. Optional in a submission. Derived from NZ Base NzOrganization (D4).

The legacy Practice Id (ZSS.1) is carried on identifier using the SA Legacy Practice Id naming system. Where both the payload and the authenticated context identify a practice and they disagree, the submission is rejected.

The patient who is the subject of a Special Authority Application. Derived from NZ Base NzPatient (D4), which supplies the NzAddress datatype and the NZ Base suburb extension.

The NHI is mandatory. Suburb is carried only in the NZ Base suburb extension - consumers SHALL NOT fall back to Address.district or parse Address.line. NHI addresses are not always validated (no fixed abode, overseas and unknown addresses), so suburb is not treated as mandatory. NzAddress building name, domicile code and geocode have no home in the Application Data schema and are dropped by the API.

A practitioner on a Special Authority Application: the Applicant (referenced from QuestionnaireResponse.author and Claim.requestor) or the Referrer (referenced from the referring-practitioner extension). Derived from NZ Base NzPractitioner (D4).

The role is carried by which element refers to the Practitioner, not by a role code (D5). Practitioner is used rather than PractitionerRole because organisational context is not required.

A registration identifier is mandatory. The registration authority is carried in Identifier.system, using the NZ Base responsible-authority naming systems (e.g. https://standards.digital.health.nz/ns/medical-council-id), and the registration number in Identifier.value.

The HPI CPN is optional in the payload. For the Applicant, where a CPN is present it SHALL agree with the CPN claim in the validated access token or the submission is rejected. No CPN is held for the Referrer.

The HNZ interpretation of a Pharmac Special Authority form at a point in time (D3), derived by the pharmac-direct-query-service.

Phase 1: the Questionnaire canonical is an identifier, not a resolvable address. No Questionnaire resource is published at the canonical URL in Phase 1; form definitions remain base64 encoded XML and MathML retrieved from the pharmac-direct-query-service. This profile documents the constraints the canonical and linkId values must satisfy.

• url is https://fhir-ig.digital.health.nz/special-authority/Questionnaire/{formNumber} and SHALL NOT contain | or #.
• version is the form version (a truncation of form_definition_sha256) and SHALL be identical, character for character, to saFormVersion. No case folding, trimming or normalisation.
• The linkId of each criterion is the criterionIdentifier: five characters, zero padded, numeric (D18).
• Criteria items are not marked required, so a partial QuestionnaireResponse is valid against the profile.

The clinical criteria and answers for a Special Authority Application. Referenced from Claim.supportingInfo.

Form identity. questionnaire carries both parts of the form identity: {canonical}|{formVersion}. The API splits on the pipe to obtain saFormNumber (the final path segment of the canonical) and saFormVersion. FHIR-native clients SHALL version-pin the canonical. It MAY be unpinned only for submissions from the SOAP to FHIR Broker, which cannot supply a form version (see Form and Criterion Identity).

Answers. Only valueBoolean and valueString answers are supported. Each answered item's linkId is the criterionIdentifier. Unanswered items are not processed. Nested items are flattened by the API, since the criterionIdentifier is unique across the whole form.

Roles. The Applicant is author (D5). The optional Referrer is the referring-practitioner extension.

Status. HSAAP Application status is never mapped to QuestionnaireResponse.status. It is always completed.

The request body of POST [base]/Claim/$submit. A collection Bundle containing the Special Authority Application (Claim), the clinical criteria and answers (QuestionnaireResponse), the Patient, the Applicant and optional Referrer (Practitioner) and the optional submitting Organization. The Bundle is accepted or rejected atomically.

All references between entries SHALL resolve within the Bundle.

The status and outcome of a Special Authority Application. Returned in the SA Response Bundle from Claim/$submit, and from Application Enquiry (GET [base]/ClaimResponse?request.identifier=...).

• HSAAP status, outcome, outcome code and outcome reason are carried in the application-status extension. The shape is identical at submission and enquiry (D22).
• existing-approval is returned only on the synchronous $submit response, where the Application was declined because a conflicting Approval exists.
• The Approval Number, once approved, is carried on identifier and preAuthRef (D23).
• error carries the single machine readable outcome code (D9). The same code and reason are also rendered in the OperationOutcome in the response Bundle.
• status, type, use, insurer and outcome are mandatory in FHIR R4. outcome is set per the mapping on the Validation and Outcomes page; it does not replace application-status.

A Special Authority Approval, returned by Approval Enquiry (GET [base]/ClaimResponse?...). Constructed fresh from the current Approval Store record on every enquiry; it is not a replay of the ClaimResponse returned at submission.

• identifier and preAuthRef carry the Approval Number; preAuthPeriod the effective and expiry dates. A lifetime Approval carries a far-future expiry date - there is no sentinel value.
• requestor is the prescribing Practitioner who authored the originating Application (D24). The provider (pharmacy) is carried in the approval-detail extension.
• Approval type, status, form number and form version are carried in the approval-detail extension (D16).
• Coverage is carried in approval-coverage only for NPPA and panel Approvals (D15).
• Approval versions are not FHIR resource versions (D17). meta.versionId is not used and vread/_history are not supported. When approval-version-state=ALL returns several versions, each is a distinct ClaimResponse and recency is carried on meta.lastUpdated (the Approval's createdOn).
• status is always active and outcome always complete. Both are mandatory in FHIR R4 and carry no HSAAP meaning; the Approval status is approval-detail.status.

Renders the single business outcome of a Special Authority Application (D9) in a $submit response. The machine readable reason (outcomeCode) is carried in issue.details.coding and the human readable reason (outcomeReason) in issue.diagnostics.

This profile does not apply to OperationOutcomes returned with HTTP 4xx/5xx for requests rejected by the API before reaching the service (e.g. profile validation failures), which may carry several issues.

The response to POST [base]/Claim/$submit. A collection Bundle containing the SA Application ClaimResponse, the OperationOutcome rendering the single outcome, and the resources the ClaimResponse references.

The HSAAP status and outcome of a Special Authority Application. The same shape is returned whether the status arrives synchronously from $submit or later through Application Enquiry (D22).

Carried on ClaimResponse. It may also be carried on Claim in Application Enquiry results so that the application-status search parameter on Claim has an element to evaluate (see Design Notes).

Coverage of an Approval, carried only for EXPLICIT_PHARMACEUTICALS, PRODUCT_CATEGORY and ALL_PHARMACEUTICALS (D15). Absent for SCHEDULE_HIERARCHY coverage: a standard CHEM/RISK Approval's coverage is re-derivable from approval-detail.formNumber and formVersion against the schedule (D6). NPPA and panel Approvals have no schedule form to derive coverage from, so their coverage is carried explicitly.

Approval facts that have no existing FHIR element, including the Approval status and the provider (pharmacy) identity (D16, D24). Approval status is carried here because ClaimResponse.status is bound to the financial resource status value set, which cannot express ACTIVE, CANCELLED or REVOKED.

formNumber and formVersion are facts about the Approval. They deliberately do not reuse the Questionnaire.url|version canonical used for submission (D16).

Detail of a conflicting Approval, returned only on the synchronous $submit response where the Application was declined because a conflicting Approval exists. Not returned on Application Enquiry (D22).

The referring practitioner for a Special Authority Application (D5). Matches the legacy PRD Referring role.

The referrer is asserted by the applicant. It is never authenticated and never verified, and neither channel establishes that the named referrer agreed to the referral. Only registration details are held for the referrer.

Indicates the applicant is requesting a waiver. Treated as false when absent.

Asserted source context for a submission. This is provenance only: it MUST NOT override the authenticated identity, and MUST NOT be used for authentication or authorisation.

The SOAP to FHIR Broker populates this from the legacy HL7 payload (ZSS.1, ZSL.1-ZSL.4, ZSU.1). Direct FHIR clients may omit it, in which case the API derives the values from the authenticated channel context.

Note: the detailed design places this extension on Bundle. In FHIR R4 Bundle is a Resource, not a DomainResource, and cannot carry extensions, so this guide places it on the focal Claim. See Design Notes.

HSAAP Application status: SUBMITTED, PENDING_REVIEW, CANCELLED or DONE. Claim.status cannot express these values. Maps to the Application Store status filter.

Range query on the Approval expiry date (preAuthPeriod.end), e.g. approval-expiring=ge2026-10-01&approval-expiring=le2026-12-31. Mutually exclusive with approval-valid-on.

Approval status: ACTIVE, CANCELLED or REVOKED, as carried in the approval-detail extension. Narrows a result set.

Matches Approvals whose preAuthPeriod contains the supplied date, i.e. preAuthPeriod.start <= date <= preAuthPeriod.end. This is containment of a single date, which differs from standard FHIR date search semantics on a Period, hence a custom parameter. Only the eq comparator is supported. Mutually exclusive with approval-expiring.

Controls which Approval versions are returned: LATEST (default), PREVIOUS or ALL. This is a result-control parameter with no FHIRPath expression - an Approval version is a new Approval Store row, not a FHIR resource version (D17). Each version is returned as a distinct ClaimResponse ordered by meta.lastUpdated. Values are from the SA Approval Version State value set.

The Applicant of the Special Authority Application. FHIR R4 Claim has no requestor element, so the Applicant is carried in Claim.provider and this parameter evaluates Claim.provider. It preserves the API contract requestor:Practitioner.identifier and _include=Claim:requestor. The chained identifier accepts the HPI CPN system or an NZ responsible-authority registration system. The core provider parameter is equivalent.

Resources referenced from Claim.supportingInfo, i.e. the QuestionnaireResponse. FHIR R4 defines no such search parameter on Claim; this parameter supports _include=Claim:supportinginfo.

Submits a Special Authority Application. The request body is an SA Submission Bundle; the response is an SA Response Bundle.

Special Authority Application Number allocated by the special-authority-application-service. The only identifier carried on Claim.identifier (D23).

All SA Application outcome codes.

Outcome of a Special Authority Application. Present only where the Application status is DONE.

All SA Application status codes.

Lifecycle status of a Special Authority Application held by the special-authority-application-service. Deliberately not mapped to QuestionnaireResponse.status or Claim.status, neither of which can distinguish PENDING_REVIEW from DONE.

All SA Approval coverage type codes returned over FHIR.

Coverage variants returned on the approval-coverage extension. SCHEDULE_HIERARCHY coverage exists in the Approval Store but is not returned over FHIR (D15) and so is not included.

Special Authority Approval Number. Carried on ClaimResponse.identifier and ClaimResponse.preAuthRef (D23).

All SA Approval status codes.

Status of a Special Authority Approval in the Approval/Entitlement Store. Carried in the approval-detail extension because ClaimResponse.status (financial resource status) cannot express these meanings.

All SA Approval type codes.

Type of Special Authority Approval (legacy ZST.8). Draft and incomplete - the design lists CHEM, HOSP, EXCP, TEMPLETON 'etc.'. The full list must be confirmed against the Approval/Entitlement Store before publication.

All SA Approval version state codes.

Values for the approval-version-state search parameter. Draft - code names other than ALL must be confirmed against the Approval Store versionState values.

Categories of Claim.supportingInfo used on a Special Authority Application.

Legacy Special Authority Practice Id (HL7 v2 ZSS.1), used on the submitting Organization.

All codes in the SA Error Code Catalogue.

Machine readable outcome codes from the single Error Code Catalogue authored and published by the special-authority-application-service (D10). The catalogue has not yet been published, so this code system is defined with content = not-present.

Pharmac Pharmacode. Placeholder URI, to be replaced by the authoritative Pharmacode system URI if one is published.

Pharmacy claimant number. Identifies the provider (pharmacy) on an Approval and is the system used by the approval-provider-id search parameter.

All SA provider id type codes.

Identifier type for the provider (pharmacy) on an Approval. Fixed to CLAIMANT_NUMBER until pharmacies move to HPI Facility numbers.

Example applicant practitioner with an HPI CPN and a Medical Council registration.

Synchronous $submit response for an approved Application.

Synchronous $submit response where the Application was declined because a conflicting Approval exists. The outcome code shown is illustrative; codes come from the Error Code Catalogue.

Application outcome returned by GET [base]/ClaimResponse?request.identifier=… while the Application awaits manual review.

A standard CHEM Approval. Coverage is not returned; it is derivable from the form number and version (D6, D15).

An exceptional circumstances (NPPA) Approval. There is no schedule form, so coverage is carried explicitly. The Approval is linked to a dispensing pharmacy.

An NPPA Application. No form declares coverage, so the requested pharmaceutical is supplied in Claim.item.

The single outcome for a declined Application, rendered as an OperationOutcome.

Clinical answers from a FHIR-native PMS. The questionnaire canonical is version pinned, and a referrer is supplied.

Example referring practitioner. Registration details only - no CPN is held for a referrer.

Response to POST [base]/Claim/$submit for an approved Application.

Response to POST [base]/Claim/$submit for a declined Application.

An illustrative, fictional Special Authority form. In Phase 1 no Questionnaire is published at the canonical URL of a real form; this example only demonstrates the url, version and linkId conventions.

Example patient using the NHI test range.

A standard Special Authority Application as submitted. No identifier (allocated by the API) and no item (coverage is derived from the form).

Request body for POST [base]/Claim/$submit from a FHIR-native PMS.

Example submitting practice with an HPI Facility identifier and a legacy Practice Id.