Generated Narrative: CapabilityStatement AIRCapabilityStatement AIR FHIR Server Capability Statement Implementation Guide Version: 2.0.0 FHIR Version: 4.0.1 Supported Formats: json, application/fhir+json Published on: 2025-06-01 Published by: 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 AIR ImmSoT FHIR R4 server. All requests require: x-api-key header (API Gateway key) OAuth2 bearer token with the appropriate scope (see security schemes) Optional: UserID, FacilityID, SourceSystemID, X-Correlation-ID headers for audit API version selection is controlled by the Api-Version header (values: 1 or 2, default: 1). Security Enable CORS: yes Security services supported: OAuth OAuth2 client credentials flow. Obtain a bearer token from the token endpoint then include it as Authorization: Bearer <token>. Summary of System-wide Interactions Supports the transactioninteraction. Summary of System-wide Operations Conformance Operation Documentation SHALL $process-message POST [base]/Immunization/$process-message Processes an incoming FHIR message Bundle (type=message) to acknowledge a previously sent immunisation update notification. Updates an existing acknowledgement record from status SENT to RECEIVED. Request body: FHIR Bundle containing a MessageHeader with response.code=ok and an OperationOutcome entry. Required scope: system/MessageHeader.u Responses: 200 OK (OperationOutcome), 401, 403, 422, 429, 500 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 Type Profile R S U C H-I Searches _include _revinclude Operations Immunization https://standards.digital.health.nz/fhir/air/StructureDefinition/air-immunization y y y y y patient, target-disease, status-reason:not-in, status:not-in, status, _query, _lastUpdated, _offset, _count, _includeMigratedData, _dqStatus, _include *, Immunization:patient, Immunization:performer, Immunization:location $upsert, $bulk-update, $match, $unmatch Patient https://standards.digital.health.nz/fhir/air/StructureDefinition/air-patient y $update-state, $reassign-schedules, $patient-history CarePlan https://standards.digital.health.nz/fhir/air/StructureDefinition/air-careplan y nhi Resource Conformance: unspecified Immunization Base System Profile AIR Immunization Profile Conformance SHALL Reference Policy logical Interaction summary Supports create POST [base]/Immunization Creates a new immunisation event. Performs validation checks before persisting. Required scope: system/Immunization.c Request headers: UserID (optional) – end-user identifier for audit FacilityID (optional) – facility where vaccination took place SourceSystemID (optional) – source system identifier (HIP Integration Application list) X-Correlation-ID (optional) – correlation UUID for tracing x-api-key (required) – API Gateway key Api-Version (optional, default=1) – API version selector (1 or 2) Responses: 201 Created – immunisation record created; Location and ETag headers returned 422 Unprocessable Entity – validation failed (OperationOutcome) 403 Forbidden – insufficient scope 429 Too Many Requests – rate limit exceeded 500 Internal Server Error read GET [base]/Immunization/{ID} Reads a single immunisation event by its ImmSoT logical ID. Returns the enriched Immunization bundle including Patient, Organization, Practitioner and Location resources when available. Required scope: system/Immunization.r Responses: 200 OK – Immunization resource (OrchestrationImmunizationBundle) 400 Bad Request 403 Forbidden 404 Not Found 429 Too Many Requests 500 Internal Server Error update PUT [base]/Immunization/{ID} Updates an existing immunisation event. Performs validation and optimistic concurrency check via the If-Match header (required, must contain the current versionId ETag). Required scope: system/Immunization.u or air-admin/Immunization.u Request headers (additional to standard): If-Match (required) – current versionId ETag, e.g. "3" To suppress data-quality re-evaluation for a known-good update, include in the request body meta.extension the dqIgnore: true flag (see UpdateDQIgnore example). Responses: 200 OK – updated Immunization resource; data-quality results in meta 400 Bad Request 401 Unauthorized 403 Forbidden 422 Unprocessable Entity – validation failure 500 Internal Server Error history-instance GET [base]/Immunization/{ID}/_history Returns all versions of an immunisation event as a FHIR history Bundle (type=history). Each bundle entry is a full Immunization resource snapshot at that version, including data-quality metadata in meta.extension. Required scope: system/Immunization.r or air-admin/Immunization.r Responses: 200 OK – Bundle (type=history) 400 Bad Request 403 Forbidden 429 Too Many Requests 500 Internal Server Error search-type POST [base]/Immunization/_search Searches for immunisation events. Supports two search modes: Standard NHI search – requires patient parameter (NHI number or full Patient reference). Optional filters: target-disease, status-reason:not-in, status:not-in. Include enriched related resources via _include. Data-quality admin search – requires _query=data-quality, _lastUpdated (range or exact), _offset, _count. Restricted to air-admin/Immunization.s scope. The request body should be application/x-www-form-urlencoded (not JSON). Both query parameters and form-body parameters are supported. Required scope: system/Immunization.s or air-admin/Immunization.s Responses: 200 OK – Bundle (type=searchset); total=0 when no records found 400 Bad Request 401 Unauthorized 403 Forbidden 429 Too Many Requests 500 Internal Server Error Documentation Core immunisation event resource. All interactions operate on FHIR Immunization resources conforming to the AIRImmunization profile. Search Parameters Conformance Parameter Type Documentation SHALL patient reference NHI number of the patient, or a full Patient reference URL. Examples: patient=ZKN2155 patient=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKN2155 When a full URL is provided it is matched against Immunization.patient.reference. SHALL target-disease token Filter by vaccine-preventable disease (system|code). Comma-separated for multiple values. E.g. http://snomed.info/sct|66071002. SHALL status-reason:not-in token Exclude immunisation events with the specified status reason codes. Accepted formats (comma-separated): system|code e.g. https://standards.digital.health.nz/ns/air-status-reason-terms|CPI |code or bare code for system-independent matching. SHALL status:not-in token Exclude immunisation events with the specified status codes. Allowed values: entered-in-error, completed, not-done. SHALL status token Used in data-quality search only. Include only events with the given status(es). Defaults to all statuses if omitted. Allowed values: entered-in-error, completed, not-done. SHALL _query special Set to data-quality to invoke the admin data-quality search. Requires air-admin/Immunization.s scope. Must be combined with _lastUpdated, _offset, and _count. SHALL _lastUpdated date Used in data-quality search. Supports eq, ge, and le prefixes. E.g. ge2023-05-11T00:25:20.641Z or le2023-06-01. SHALL _offset number Used in data-quality search. Number of records to skip. Default: 0. SHALL _count number Used in data-quality search. Maximum records to return (1–100). Default: 100. SHALL _includeMigratedData string Used in data-quality search only. Set to true to include migrated data. Default: false. SHALL _dqStatus token Used in data-quality search only. Filter by data quality status. Allowed values: I (Identified), A (Accepted), P (Passed). Comma-separated. SHALL _include string Include related resources in the response. Supported values: Patient, Immunization:performer, Immunization:location. E.g. _include=Patient. Combined Search Parameters Conformance Parameters Types patient reference patient(+target-disease+status-reason:not-in+status:not-in+_include) reference(+token+token+token+string) _query+_lastUpdated+_offset+_count(+_includeMigratedData+_dqStatus+status) special+date+number+number(+string+token+token) Extended Operations Conformance Operation Documentation SHALL $upsert POST [base]/Immunization/$upsert Performs an upsert using a deterministic matching algorithm (NHI + occurrence date + vaccine code + indication): No match → create new event Single match → update the matched event Multiple matches → create new event (duplicate DQ violation raised) Processing failure → reject the request Required scope: system/Immunization.c + system/Immunization.u Responses: 200 OK (updated) or 201 Created (inserted), 400, 403, 422, 429, 500 SHALL $bulk-update POST [base]/Immunization/$bulk-update Atomic bulk create/upsert of immunisation events. Request body is a FHIR Parameters resource (application/x-www-form-urlencoded). Each parameter entry has name create or upsert with a contained Immunization resource: create → always creates a new event upsert → applies the same matching algorithm as $upsert The entire operation is atomic: if any event fails, the whole request is rejected. Required scope: system/Immunization.c + system/Immunization.u Responses: 200 OK (Parameters resource with created/updated entries), 400, 403, 429, 500 SHALL $match POST [base]/Immunization/{ID}/$match Manually matches an immunisation event to a planned event in the consumer's vaccination schedule. Request body: FHIR Parameters with version (string), plannedEventId (string), and reason.code (string). Required scope: system/Immunization.c + system/Immunization.u Responses: 200 OK (Bundle), 400, 403, 429, 500 SHALL $unmatch POST [base]/Immunization/{ID}/$unmatch Manually unmatches an immunisation event from a planned event. Request body: same structure as $match with an unmatch reason code. Required scope: system/Immunization.c + system/Immunization.u Responses: 200 OK (Bundle), 400, 403, 429, 500 Resource Conformance: unspecified Patient Base System Profile AIR Patient Profile Profile Conformance SHALL Reference Policy Interaction summary Supports read GET [base]/Patient/{NHI} Reads the current state of an ImmSoT consumer (returned as a FHIR Patient conforming to AIRPatient). When the optional origin-nhi-version request header is supplied, the API compares it against the stored NHI version: Same version → return cached data Different version → sync with NHI, update ImmSoT, return fresh data Required scope: system/Patient.r Responses: 200 OK, 400, 403, 404, 429, 500 Documentation ImmSoT consumer (patient) resource. Stores NHI-linked consumer state, sub-status, and schedule information. Extended Operations Conformance Operation Documentation SHALL $update-state POST [base]/Patient/{NHI}/$update-state Updates a consumer's state and/or sub-status. Uses optimistic locking: the version parameter must match the server's current version, otherwise a 412 Precondition Failed is returned. At least one of state or subStatus must be specified. Omitting one leaves it unchanged. Set subStatus to null to clear it. Request body: FHIR Parameters with version (integer), optionally state (string), optionally subStatus (string). Required scope: system/Patient.u Responses: 200 OK (Patient), 400, 403, 404, 412 Precondition Failed, 429, 500 SHALL $reassign-schedules POST [base]/Patient/{NHI}/$reassign-schedules Reassigns a consumer's immunisation schedules. Cancels existing schedules (including manual matches and MQ records) and creates new ones based on the supplied onboarding date. The schedule repair service is then run to regenerate matches against the new plan. Note: Any manual match linked to a cancelled planned event is also unmatched. Request body: FHIR Parameters with reassignDate (date). Required scope: air-admin/Patient.u or system/Patient.u Responses: 200 OK (Patient), 400, 403, 429, 500 SHALL $patient-history GET [base]/Patient/{NHI}/_history Returns all versions of an ImmSoT consumer as a FHIR history Bundle. Each entry is a full Patient snapshot including modification audit metadata (air-modified-by, air-modified-source-system) in meta.extension. Required scope: air-admin/Patient.r or system/Patient.r Responses: 200 OK (Bundle, type=history), 400, 403, 429, 500 Resource Conformance: unspecified CarePlan Base System Profile AIR CarePlan Profile Profile Conformance SHALL Reference Policy Interaction summary Supports search-type GET [base]/CarePlan/$view?nhi={NHI} Returns the consumer's full immunisation plan as a Bundle containing CarePlan, Immunization, and ImmunizationRecommendation resources. Required scope: system/CarePlan.s Responses: 200 OK (CarePlanBundle), 400, 403, 429, 500 Documentation Read a consumer's immunisation plan (schedule). Each CarePlan represents a single Antigen Group Vaccination (AGV) schedule and links planned ImmunizationRecommendation events and administered Immunization resources. Search Parameters Conformance Parameter Type Documentation SHALL nhi token NHI identifier of the patient/consumer whose immunisation plan to retrieve. Required. FHIR Messaging Capabilities Messaging Capability Supported Message(s) Mode Definition sender https://standards.digital.health.nz/fhir/MessageDefinition/UpdateImmunisationRequestMessageDefinition sender https://standards.digital.health.nz/fhir/MessageDefinition/UpdateImmunisationResponseMessageDefinition Documentation AIR supports HL7 FHIR messaging for immunisation update notifications sent to enrolled consumers and providers.
The Aotearoa Immunisation Register (AIR) FHIR R4 API (ImmSoT). API versioning: - Internal Health NZ consumers call https://air.api.digital.health.nz/fhir/R4. Omit Api-Version header (or set Api-Version=1) for v1 behaviour; set Api-Version=2 for v2. - External consumers call https://api.air.digital.health.nz/s2s/fhir/R4 (v1) or https://api.air.digital.health.nz/s2s/fhir/R4/v2 (v2). Both external paths are gateway routes that forward to the internal /fhir/R4 backend.
Defines the capabilities of the AIR ImmSoT FHIR server so that clients can discover supported interactions, search parameters, and custom operations.
© 2025 Health New Zealand | Te Whatu Ora
AIR ImmSoT FHIR R4 server. All requests require: - x-api-key header (API Gateway key) - OAuth2 bearer token with the appropriate scope (see security schemes) - Optional: UserID, FacilityID, SourceSystemID, X-Correlation-ID headers for audit API version selection is controlled by the Api-Version header (values: 1 or 2, default: 1).
OAuth2 client credentials flow. Obtain a bearer token from the token endpoint then include it as Authorization: Bearer <token>.
Core immunisation event resource. All interactions operate on FHIR Immunization resources conforming to the AIRImmunization profile.
**POST** `[base]/Immunization` Creates a new immunisation event. Performs validation checks before persisting. **Required scope:** `system/Immunization.c` **Request headers:** - `UserID` (optional) – end-user identifier for audit - `FacilityID` (optional) – facility where vaccination took place - `SourceSystemID` (optional) – source system identifier (HIP Integration Application list) - `X-Correlation-ID` (optional) – correlation UUID for tracing - `x-api-key` (required) – API Gateway key - `Api-Version` (optional, default=1) – API version selector (1 or 2) **Responses:** - `201 Created` – immunisation record created; Location and ETag headers returned - `422 Unprocessable Entity` – validation failed (OperationOutcome) - `403 Forbidden` – insufficient scope - `429 Too Many Requests` – rate limit exceeded - `500 Internal Server Error`
**GET** `[base]/Immunization/{ID}` Reads a single immunisation event by its ImmSoT logical ID. Returns the enriched Immunization bundle including Patient, Organization, Practitioner and Location resources when available. **Required scope:** `system/Immunization.r` **Responses:** - `200 OK` – Immunization resource (OrchestrationImmunizationBundle) - `400 Bad Request` - `403 Forbidden` - `404 Not Found` - `429 Too Many Requests` - `500 Internal Server Error`
**PUT** `[base]/Immunization/{ID}` Updates an existing immunisation event. Performs validation and optimistic concurrency check via the `If-Match` header (required, must contain the current versionId ETag). **Required scope:** `system/Immunization.u` or `air-admin/Immunization.u` **Request headers (additional to standard):** - `If-Match` (required) – current versionId ETag, e.g. `"3"` To suppress data-quality re-evaluation for a known-good update, include in the request body `meta.extension` the `dqIgnore: true` flag (see UpdateDQIgnore example). **Responses:** - `200 OK` – updated Immunization resource; data-quality results in meta - `400 Bad Request` - `401 Unauthorized` - `403 Forbidden` - `422 Unprocessable Entity` – validation failure - `500 Internal Server Error`
**GET** `[base]/Immunization/{ID}/_history` Returns all versions of an immunisation event as a FHIR history Bundle (type=history). Each bundle entry is a full Immunization resource snapshot at that version, including data-quality metadata in `meta.extension`. **Required scope:** `system/Immunization.r` or `air-admin/Immunization.r` **Responses:** - `200 OK` – Bundle (type=history) - `400 Bad Request` - `403 Forbidden` - `429 Too Many Requests` - `500 Internal Server Error`
**POST** `[base]/Immunization/_search` Searches for immunisation events. Supports two search modes: **Standard NHI search** – requires `patient` parameter (NHI number or full Patient reference). Optional filters: `target-disease`, `status-reason:not-in`, `status:not-in`. Include enriched related resources via `_include`. **Data-quality admin search** – requires `_query=data-quality`, `_lastUpdated` (range or exact), `_offset`, `_count`. Restricted to `air-admin/Immunization.s` scope. The request body should be `application/x-www-form-urlencoded` (not JSON). Both query parameters and form-body parameters are supported. **Required scope:** `system/Immunization.s` or `air-admin/Immunization.s` **Responses:** - `200 OK` – Bundle (type=searchset); total=0 when no records found - `400 Bad Request` - `401 Unauthorized` - `403 Forbidden` - `429 Too Many Requests` - `500 Internal Server Error`
NHI number of the patient, or a full Patient reference URL. Examples: - `patient=ZKN2155` - `patient=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKN2155` When a full URL is provided it is matched against `Immunization.patient.reference`.
Filter by vaccine-preventable disease (system|code). Comma-separated for multiple values. E.g. `http://snomed.info/sct|66071002`.
Exclude immunisation events with the specified status reason codes. Accepted formats (comma-separated): - `system|code` e.g. `https://standards.digital.health.nz/ns/air-status-reason-terms|CPI` - `|code` or bare `code` for system-independent matching.
Exclude immunisation events with the specified status codes. Allowed values: `entered-in-error`, `completed`, `not-done`.
Used in data-quality search only. Include only events with the given status(es). Defaults to all statuses if omitted. Allowed values: `entered-in-error`, `completed`, `not-done`.
Set to `data-quality` to invoke the admin data-quality search. Requires `air-admin/Immunization.s` scope. Must be combined with `_lastUpdated`, `_offset`, and `_count`.
Used in data-quality search. Supports `eq`, `ge`, and `le` prefixes. E.g. `ge2023-05-11T00:25:20.641Z` or `le2023-06-01`.
Used in data-quality search. Number of records to skip. Default: 0.
Used in data-quality search. Maximum records to return (1–100). Default: 100.
Used in data-quality search only. Set to `true` to include migrated data. Default: `false`.
Used in data-quality search only. Filter by data quality status. Allowed values: `I` (Identified), `A` (Accepted), `P` (Passed). Comma-separated.
Include related resources in the response. Supported values: `Patient`, `Immunization:performer`, `Immunization:location`. E.g. `_include=Patient`.
**POST** `[base]/Immunization/$upsert` Performs an upsert using a deterministic matching algorithm (NHI + occurrence date + vaccine code + indication): 1. No match → create new event 2. Single match → update the matched event 3. Multiple matches → create new event (duplicate DQ violation raised) 4. Processing failure → reject the request **Required scope:** `system/Immunization.c` + `system/Immunization.u` **Responses:** `200 OK` (updated) or `201 Created` (inserted), `400`, `403`, `422`, `429`, `500`
**POST** `[base]/Immunization/$bulk-update` Atomic bulk create/upsert of immunisation events. Request body is a FHIR Parameters resource (`application/x-www-form-urlencoded`). Each parameter entry has name `create` or `upsert` with a contained Immunization resource: - `create` → always creates a new event - `upsert` → applies the same matching algorithm as `$upsert` The entire operation is atomic: if any event fails, the whole request is rejected. **Required scope:** `system/Immunization.c` + `system/Immunization.u` **Responses:** `200 OK` (Parameters resource with `created`/`updated` entries), `400`, `403`, `429`, `500`
**POST** `[base]/Immunization/{ID}/$match` Manually matches an immunisation event to a planned event in the consumer's vaccination schedule. Request body: FHIR Parameters with `version` (string), `plannedEventId` (string), and `reason.code` (string). **Required scope:** `system/Immunization.c` + `system/Immunization.u` **Responses:** `200 OK` (Bundle), `400`, `403`, `429`, `500`
**POST** `[base]/Immunization/{ID}/$unmatch` Manually unmatches an immunisation event from a planned event. Request body: same structure as `$match` with an unmatch reason code. **Required scope:** `system/Immunization.c` + `system/Immunization.u` **Responses:** `200 OK` (Bundle), `400`, `403`, `429`, `500`
ImmSoT consumer (patient) resource. Stores NHI-linked consumer state, sub-status, and schedule information.
**GET** `[base]/Patient/{NHI}` Reads the current state of an ImmSoT consumer (returned as a FHIR Patient conforming to AIRPatient). When the optional `origin-nhi-version` request header is supplied, the API compares it against the stored NHI version: - Same version → return cached data - Different version → sync with NHI, update ImmSoT, return fresh data **Required scope:** `system/Patient.r` **Responses:** `200 OK`, `400`, `403`, `404`, `429`, `500`
**POST** `[base]/Patient/{NHI}/$update-state` Updates a consumer's state and/or sub-status. Uses optimistic locking: the `version` parameter must match the server's current version, otherwise a `412 Precondition Failed` is returned. At least one of `state` or `subStatus` must be specified. Omitting one leaves it unchanged. Set `subStatus` to null to clear it. Request body: FHIR Parameters with `version` (integer), optionally `state` (string), optionally `subStatus` (string). **Required scope:** `system/Patient.u` **Responses:** `200 OK` (Patient), `400`, `403`, `404`, `412 Precondition Failed`, `429`, `500`
**POST** `[base]/Patient/{NHI}/$reassign-schedules` Reassigns a consumer's immunisation schedules. Cancels existing schedules (including manual matches and MQ records) and creates new ones based on the supplied onboarding date. The schedule repair service is then run to regenerate matches against the new plan. **Note:** Any manual match linked to a cancelled planned event is also unmatched. Request body: FHIR Parameters with `reassignDate` (date). **Required scope:** `air-admin/Patient.u` or `system/Patient.u` **Responses:** `200 OK` (Patient), `400`, `403`, `429`, `500`
**GET** `[base]/Patient/{NHI}/_history` Returns all versions of an ImmSoT consumer as a FHIR history Bundle. Each entry is a full Patient snapshot including modification audit metadata (`air-modified-by`, `air-modified-source-system`) in `meta.extension`. **Required scope:** `air-admin/Patient.r` or `system/Patient.r` **Responses:** `200 OK` (Bundle, type=history), `400`, `403`, `429`, `500`
Read a consumer's immunisation plan (schedule). Each CarePlan represents a single Antigen Group Vaccination (AGV) schedule and links planned ImmunizationRecommendation events and administered Immunization resources.
**GET** `[base]/CarePlan/$view?nhi={NHI}` Returns the consumer's full immunisation plan as a Bundle containing CarePlan, Immunization, and ImmunizationRecommendation resources. **Required scope:** `system/CarePlan.s` **Responses:** `200 OK` (CarePlanBundle), `400`, `403`, `429`, `500`
NHI identifier of the patient/consumer whose immunisation plan to retrieve. Required.
**POST** `[base]/Immunization/$process-message` Processes an incoming FHIR message Bundle (type=message) to acknowledge a previously sent immunisation update notification. Updates an existing acknowledgement record from status `SENT` to `RECEIVED`. Request body: FHIR Bundle containing a MessageHeader with `response.code=ok` and an OperationOutcome entry. **Required scope:** `system/MessageHeader.u` **Responses:** `200 OK` (OperationOutcome), `401`, `403`, `422`, `429`, `500`
AIR supports HL7 FHIR messaging for immunisation update notifications sent to enrolled consumers and providers.