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

CapabilityStatement: HSAAP Special Authority FHIR API

Official URL: https://fhir-ig.digital.health.nz/special-authority/CapabilityStatement/SpecialAuthorityFHIRAPICapabilityStatement Version: 0.1.1
Draft as of 2026-10-15 Computable Name: SpecialAuthorityFHIRAPICapabilityStatement

Health NZ Te Whatu Ora Special Authority FHIR API

Raw OpenAPI-Swagger Definition file | Download

Special Authority FHIR Server Capability Statement

  • Implementation Guide Version: 0.1.1
  • FHIR Version: 4.0.1
  • Supported Formats: application/fhir+json
  • Published on: 2026-10-15
  • Published by: Health New Zealand | Te Whatu Ora

Note to Implementers: FHIR Capabilities

Any FHIR capability may be 'allowed' by the system unless explicitly marked as 'SHALL NOT'. A few items are marked as MAY in the Implementation Guide to highlight their potential relevance to the use case.

FHIR RESTful Capabilities

Mode: server

All token searches on identifiers SHALL be system-qualified (system|value). All requests require a validated access token and a validated signed Request-Context header.

Security
Enable CORS: no
Security services supported: SMART-on-FHIR

OAuth 2.0 client credentials flow and signed Request-Context header, per the Health NZ Digital Services Hub onboarding process. The authenticated requester identity is never taken from the FHIR payload.

Capabilities by Resource/Profile

Summary

The summary table lists the resources that are part of this configuration, and for each resource it lists:

  • The relevant profiles (if any)
  • The interactions supported by each resource (Read, Search, Update, and Create, are always shown, while VRead, Patch, Delete, History on Instance, or History on Type are only present if at least one of the resources has support for them.
  • The required, recommended, and some optional search parameters (if any).
  • The linked resources enabled for _include
  • The other resources enabled for _revinclude
  • The operations on the resource (if any)
Resource TypeProfileRSUCSearches_include_revincludeOperations
Claimhttps://fhir-ig.digital.health.nz/special-authority/StructureDefinition/sa-claim
Additional supported profiles:
  SA Claim		yidentifier, patient, requestor, application-status, createdClaim:patient, Claim:requestor, Claim:supportinginfo$submit
ClaimResponseSupported Profiles
  SA Application ClaimResponse
  SA Approval ClaimResponse		yidentifier, request, patient, requestor, approval-status, approval-valid-on, approval-expiring, approval-provider-id, approval-version-state, _elementsClaimResponse:request
Base System Profile
SA Claim
Profile Conformance
SHALL
Reference Policy

Supported Profiles

SA Claim

Interaction summary
  • Supports
    search-type

    Search Applications, or retrieve a submitted Application by Application Number with _include. Search results are summary representations: referenced resources are only resolved via _include.

Documentation

Special Authority Applications. Submitted with $submit; enquired with search.

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

Application Number. SHALL be system-qualified.

SHALLpatientreference

Supports the chained form patient.identifier=nhi-system|NHI only.

SHALLrequestorreference

Supports requestor:Practitioner.identifier with the HPI CPN system or an NZ registration authority system.

SHALLapplication-statustoken

SUBMITTED | PENDING_REVIEW | CANCELLED | DONE

SHALLcreateddate

Submission date range: ge and le map to submittedFrom and submittedTo.

 
Extended Operations
ConformanceOperationDocumentation
SHALL$submit
Core FHIR Resource
ClaimResponse
Reference Policy
Interaction summary
  • Supports search-type.

Supported Profiles

SA Application ClaimResponse
SA Approval ClaimResponse

Documentation

Application outcomes (searched by request.identifier) and Approvals (searched by Approval Number, NHI or practitioner). An Approval search SHALL supply at least one of identifier, patient.identifier or requestor:Practitioner.identifier. approval-valid-on and approval-expiring are mutually exclusive.

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

Approval Number. SHALL be system-qualified.

SHALLrequestreference

Supports the chained form request.identifier=application-number-system|applicationNumber.

SHALLpatientreference

Supports the chained form patient.identifier=nhi-system|NHI only.

SHALLrequestorreference

Supports requestor:Practitioner.identifier with the HPI CPN system or an NZ registration authority system.

SHALLapproval-statustoken

ACTIVE | CANCELLED | REVOKED

SHALLapproval-valid-ondate

Approvals valid on the supplied date.

SHALLapproval-expiringdate

Approvals expiring within a date range.

SHALLapproval-provider-idtoken

Provider - pharmacy - on the Approval. SHALL be system-qualified.

SHALLapproval-version-statetoken

LATEST - default - or PREVIOUS or ALL.

SHALL_elementsspecial

Supported for Retrieve Application Outcome: _elements=extension,preAuthRef.