Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V2)
2.0.0 - release New Zealand

Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V2) - Local Development build (v2.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

API


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.


REST APIs



Resource Level Interactions

Immunization

Core immunisation event resource. All interactions operate on FHIR Immunization resources conforming to the AIRImmunization profile.


Interactions
CodeVerbURLDocumentation
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`
Operations
NameDefinitionDocumentation
upsert ​ https://standards.digital.health.nz/fhir/air/OperationDefinition/immunization-upsert

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
bulk-update ​ https://standards.digital.health.nz/fhir/air/OperationDefinition/immunization-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
match ​ https://standards.digital.health.nz/fhir/air/OperationDefinition/immunization-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
unmatch ​ https://standards.digital.health.nz/fhir/air/OperationDefinition/immunization-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
Search Parameters
NameTypeDocumentation
patient reference
Definition: http://hl7.org/fhir/SearchParameter/Immunization-patient

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.
target-disease token
Definition: http://hl7.org/fhir/SearchParameter/Immunization-target-disease

Filter by vaccine-preventable disease (system|code). Comma-separated for multiple values. E.g. http://snomed.info/sct|66071002.
status-reason:not-in token
Definition: http://hl7.org/fhir/SearchParameter/Immunization-StatusReason

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.
status:not-in token
Definition: http://hl7.org/fhir/SearchParameter/Immunization-Status

Exclude immunisation events with the specified status codes. Allowed values: entered-in-error, completed, not-done.
status token
Definition: http://hl7.org/fhir/SearchParameter/Immunization-status

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.
_query special
Definition: https://standards.digital.health.nz/fhir/air/SearchParameter/Immunization-data-quality

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.
_lastUpdated date
Definition: http://hl7.org/fhir/SearchParameter/Resource-lastUpdated

Used in data-quality search. Supports eq, ge, and le prefixes. E.g. ge2023-05-11T00:25:20.641Z or le2023-06-01.
_offset number
Definition: http://hl7.org/fhir/SearchParameter/Resource-offset

Used in data-quality search. Number of records to skip. Default: 0.
_count number
Definition: http://hl7.org/fhir/SearchParameter/Resource-count

Used in data-quality search. Maximum records to return (1–100). Default: 100.
_includeMigratedData string
Definition: https://standards.digital.health.nz/fhir/air/SearchParameter/Immunization-includeMigratedData

Used in data-quality search only. Set to true to include migrated data. Default: false.
_dqStatus token
Definition: https://standards.digital.health.nz/fhir/air/SearchParameter/Immunization-dqStatus

Used in data-quality search only. Filter by data quality status. Allowed values: I (Identified), A (Accepted), P (Passed). Comma-separated.
_include string
Definition: http://hl7.org/fhir/SearchParameter/Resource-include

Include related resources in the response. Supported values: Patient, Immunization:performer, Immunization:location. E.g. _include=Patient.
Search includes
Name
*
Immunization:patient
Immunization:performer
Immunization:location
These are the _include parameters that are supported on searches

Patient

ImmSoT consumer (patient) resource. Stores NHI-linked consumer state, sub-status, and schedule information.


Interactions
CodeVerbURLDocumentation
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`
Operations
NameDefinitionDocumentation
update-state ​ https://standards.digital.health.nz/fhir/air/OperationDefinition/update-patient-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
reassign-schedules ​ https://standards.digital.health.nz/fhir/air/OperationDefinition/reassign-patient-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
patient-history ​ https://standards.digital.health.nz/fhir/air/OperationDefinition/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
CarePlan

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.


Interactions
CodeVerbURLDocumentation
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`
Search Parameters
NameTypeDocumentation
nhi token
Definition: https://standards.digital.health.nz/fhir/air/SearchParameter/CarePlan-nhi

NHI identifier of the patient/consumer whose immunisation plan to retrieve. Required.

Server Level Interactions

Operations
NameDefinitions

process-message

http://hl7.org/fhir/OperationDefinition/MessageHeader-process-message

Messages

Definitions
NameDefinitions

sender

https://standards.digital.health.nz/fhir/MessageDefinition/UpdateImmunisationRequestMessageDefinition

sender

https://standards.digital.health.nz/fhir/MessageDefinition/UpdateImmunisationResponseMessageDefinition