Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V1)
1.28.0-SNAPSHOT - ci-build New Zealand

Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V1) - Local Development build (v1.28.0-SNAPSHOT) 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

Code | Verb | URL | Documentation
--- | --- | --- | ---
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
Name | Definition | Documentation
--- | --- | ---
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): 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`
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

Name | Type | Documentation
--- | --- | ---
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

Code | Verb | URL | Documentation
--- | --- | --- | ---
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
Name | Definition | Documentation
--- | --- | ---
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

Code | Verb | URL | Documentation
--- | --- | --- | ---
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

Name | Type | Documentation
--- | --- | ---
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

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

### Messages

Definitions

Name | Definitions
--- | ---
sender | https://standards.digital.health.nz/fhir/MessageDefinition/UpdateImmunisationRequestMessageDefinition
sender | https://standards.digital.health.nz/fhir/MessageDefinition/UpdateImmunisationResponseMessageDefinition