The Aotearoa Immunisation Register (AIR) FHIR v4.0.1 API

An operation to bulk update or insert Immunization resources.

Fetch all the versions of an ImmSOT Patient/Consumer.

    Modification information is included in the fetched dataset. Input is a valid NHI.

Reassign immunisation schedules for a patient.

    Cancels the existing schedules and then creates a new set of schedules based on the new onboarding date. Input is the new onboarding date.

An operation to search for Immunisation events that have data quality issues by date range.

Update the current state of an ImmSOT Consumer.

    Updates the Consumer state and/or sub status only. Input is the Consumer version previously read (used for operation optimistic locking) and the desired Consumer state.

    At least one of **state** and **subStatus** must be specified. If **state** or **subStatus** is not specified, then these attributes will not be updated. Setting subStatus to null will clear the current sub status.

An operation to update or insert Immunization resources.

Defines a message used to notify subscribers of an update to a patient’s vaccination record

Defines a message used to respond to a notification of an update to a patient’s vaccination record

This search parameter excludes Immunizations with specified status(es). Used in standard search only

The FHIR CarePlan resource is used as a structured representation of a consumer’s assigned immunisation schedule, supporting the coordination, tracking, and delivery of vaccinations across various antigen groups. Within the immunisation domain, each CarePlan defines a specific Antigen Group Vaccination (AGV) schedule for an individual and organizes all related vaccination activities into a coherent and accessible format. In this context, the CarePlan serves as a central framework that brings together planned immunisation events and their corresponding recorded vaccine administrations. Planned events are represented using ImmunizationRecommendation resources, indicating doses that are scheduled based on clinical guidelines and timing. When a vaccine dose is administered, the corresponding Immunization resource is linked back to the relevant planned activity in the CarePlan. This approach ensures that each vaccination event is traceable and that care delivery is aligned with national immunisation protocols. Each CarePlan acts as a living record of a consumer's immunisation journey for a particular antigen group, capturing past, present, and future planned doses. The activities within the CarePlan are typically ordered by due date, offering a clear and chronological view of the vaccination schedule. This helps healthcare providers monitor compliance, identify overdue or upcoming vaccinations, and coordinate follow-up actions. Additionally, the CarePlan supports automation and interoperability. When a consumer is onboarded into the immunisation system, relevant AGV schedules are automatically assigned, and CarePlans are created to reflect the full scope of required vaccinations.This profile on the FHIR R4 CarePlan resource adds two extensions from the R5+ CarePlan to more easily represent Immunization and ImmunizationRecommendation links, and to be better aligned with the future direction of FHIR.

This is the AIR Immunization Profile, to be used for immunisation records inbound to ImmSoT. It includes a number of constraints designed to enforce ImmSoT's lean data model approach.

AIR uses this immunizationRecommendation profile to communicate the details of scheduled events. The specification for this profile is available at https://mohits.atlassian.net/wiki/spaces/NIS/pages/3507781730/AIRImmunizationRecommendation+FHIR+API+into+ImmSOT.

Ths profile constrains the NZ Location Profile to meet the requirements of AIR as documented at https://mohits.atlassian.net/wiki/spaces/NIS/pages/3445141172/Immunisation+Event+Data+Fields.

This profile derived from MessageHeader implements extensions to message header required for Immunisation event messaging.

This profile derived from NZPatient implements the requirements of the Aotearoa Immunisation Register (AIR) Immunisation Source of Truth (ImmSoT).

This profile derived from NZPractitioner implements the requirements of the Aotearoa Immunisation Register (AIR) Immunisation Source of Truth (ImmSoT).

This profile of the FHIR R4 RelatedPerson resource includes only the fields used in AIR. The AIR use of this profile specifically includes the use cases covered by the NK1 segment in NIR HL7v2 messaging.

This profile on the FHIR r4 Observation resource serves to exchange serology report information in support of the legacy NIR data flow that attaches serology info to an existing immunization record and re-sends it. It is cut down substantially from the base Observation resource.

Defines a dose recommendation in an immunization schedule.

Defines an immunization schedule with a series of doses, including custom extensions.

This profile is for testing the design of the ImmunizationRecommendation profile that will be used to convey information about planned events.

This extension to the AIR Immunization profile pre-adopts the FHIR R5 construct of the same name. In AIR, the (mandatory) vaccineCode element should be used to transmit a CVX or NZVX code for the vaccine, while the (optional) administeredProduct element should be used to transmit an NZMT TPUU code fot he vaccine.

This extension calculates the patient age when a vaccination was administered. Although this could be calculated by the client based on patient date of birth, it is provided as a convenience.

Describes the antigen group used in AGVS.

This extension to the AIR ImmunizationRecommendation profile is used to convey information about the antigen group vaccination schedule associated with a Scheduled Event, including the schedule type, the series type, the antigen group, and the version.

This extension is used in AIR to indicate the Air Patient (AKA Consumer) as having opted off NIR before they were migrated into AIR. Presence of this extension on the AIR Patient indicates that the consumer has opted off NIR and the extension includes the date that the consumer requested this to occur.

This extension is used in AIR to communicate the current state of an AIR Patient (AKA Consumer).

This extension is used in AIR to communicate the current sub status of an AIR Patient (AKA Consumer).

This extension is used in AIR to record the user who created the immunisation event record.

This extension is used in AIR to record the system or software used to create the immunisation event record. Example values are ISM, PMS, and so on.

This describes an instance of an immunisation record violating one or more AIR data quality rules. Each such violation is described by a code, a type, a message, a pointer to the targeted element, and a weight. Refer to Data Quality Rules for codes that could be returned.

This describes one particular AIR data quality rule violation for an Immunization. Each rule violation includes a code, a type, a message, the FHIRPath expression to the element where the error occurred, and the weighting associated with the rule. Refer to Data Quality Rules and AIR Data Quality Violation Code value set for codes and messages that could be returned.

The disease which a vaccine covers. Needed in ImmunizationRecommendation as the cardinality there is only single.

This extension is used in AIR to record the user who modified the immunisation event or patient record.

This extension is used in AIR to record the system or software used to update the immunisation event or patient record. Example values are ISM, PMS, and so on.

This extension is to hold the id of an individual Scheduled Event that is surfaced by AIR as part of an ImmunizationRecommendation resource.

This extension is to be used for communicating related person info in an AIR Immunisation Event. It holds the information transmitted in the HL7v2 NK1 segment.

This extension is used on an AIR Immunization resource that is sent to AIR as part of a $bulk-update operation. It holds the date to which the Immunisation Event has been rescheduled.

The extension to the AIR ImmunizationRecommendation profile is used to convey information about scheduled events, including the event type, the schedule type, the series type, and the antigen group.

Describes the series type used in AGVS.

Describes the series type used in AGVS.

This extension allows an AIR Immunization instance to contain information from a serology report that describes a patient's expected level of immune protection from Hepatitis B infection. Note that this extension could be updated to cover additional diseases in the future.

Describes the trigger type used in AGVS.

Indicates which parties should be notified of the event

The data quality assessment of this immunization record as calculated by AIR rules.

Immunization Diluent

Immunization Facility Mobile Site

This Performed Activity adds an R5 field to the R4 CarePlan so that we can refer to an Immunization.

This Planned Activity Reference adds an R5 field to the R4 CarePlan so that we can refer to an ImmunizationRecommendation.

The match of a planned event to an immunisation event as calculated by AIR rules.

The match quality of a planned event to an immunisation event as calculated by AIR rules.

Describes the schedule type used in AGVS.

NZMT TPUU codes for use in populating the administeredProduct element in an AIR Immunization resource.

SNOMED CT Codes used in AIR to identify an Antigen Group. These codes are drawn from the SNOMED medicinal product hierarchy. The AIR Antigen Group is used in the ImmunizationRecommendation resource that is produced when a user requests a patient's list of Planned Events.

Body sites value set for AIR immunisations

Represents the current state of an AIR Consumer.

Represents the current sub status of an AIR Consumer.

Diseases that are covered by the immunization programmes and schedules that are managed or referred to in the AIR system.

This value set includes the codes used in AIR to communicate the status of a planned event.

This value set holds health worker function codes used in legacy NIR messaging. Its purpose in AIR is to enable a mapping to semantically equivalent AIR Terms codes. These codes should NOT be used in FHIR payloads.

This value set holds legacy health worker function codes. Its purpose in AIR is to enable a mapping to semantically equivalent AIR Terms codes. These codes should NOT be used in FHIR payloads.

Coded values to describe the reason an immunisation was given. Initially drawn from legacy NIR codes and CIR SNOMED codes.

A value set of codes for the functions performed by the people who are involved in administering immunisations in Aotearoa. Note that the preferred terms are AP, OP, VC, VHW and IP. The other terms in this value set will be deprecated in the future. Note that the following codes are considered as Administering Providers: AP, IP, LMC, OIS, PV, VC, VHW, WCP. The following code is considered an Ordering Provider: GP.

Coded values to describe the dates associated with a Planned Event, such as the Due Date, the Earliest Date to Give, and so on. Also codes pretaining to the Planned Event record in AIR, such as the date it was created and the date the Planned Event moved in Final status.

This Value Set contains meta tags that AIR uses to signal processing outcomes.

This value set is used to encode the relationship of a related person to the vaccine consumer. It is a subset of the FHIR Patient Relationship Type value set and includes some customised codes and displays for NZ usage.

A value set to hold the legacy HL7v2 codes for route of admin.

Route of administration value set for AIR immunisations

This value set lists the codes to be used to describe scheduled event type in AIR.

This value set includes all codes from the AIR Serology Protection code system.

Values to use in the status reason field of an immunisation event.

Allowable values for CVX and NZVX codes used to populate the vaccineCode element in an AIR Immunization resource.

Hl7v2_result Result Code

This is a code system for representing the type of AGVS attached to a Scheduled Event

This is a code system for representing the type of AGVS schedule attached to a Scheduled Event

This is a code system for representing the type of AGVS series attached to a Scheduled Event

This is a code system for representing the current state of an AIR Patient (AKA Consumer).

This is a code system for representing the current sub status of an AIR Patient (AKA Consumer).

Identifies AIR events.

This code system includes the codes used in AIR to communicate a planned event status that are not already included in http://terminology.hl7.org/CodeSystem/immunization-recommendation-status.

Describes the action taken by Orchestration server in response to an Immunisation Notification request message

Describes the AIR-specific errors

This code system includes the codes used in AIR to communicate a date associated with a planned event, such as the due date or the earliest date to give.

This code system includes values for the types of Planned Events used in AIR.

This Code System contains meta tags that AIR uses to signal processing outcomes

This code system includes the relationship type codes used in the NIR HL7v2 messasing NK1 segment Relationship field.

This local code system includes the terms used in legacy HL7 messages and FHIR requests related to serology reports for protection status for diseases such as Hepatitis B.

This AIR code system includes the terms used in NIR HL7v2 messages to populate the RXA-18 field and and in FHIR payloads to populate immunization.statusReason.

This is a code system for terms needed in AIR ImmSoT that don't come from an external standard

Hl7v2 Result Code

Antigen code set for vaccines administered in New Zealand (NZVX).

This maps the codes used to report serology protection status in NIR HL7v2 messaging (OBX-5) to the counterpart codes used in the FHIR observation.interpretation field. Note that this map only includes those codes where the code is different between HL7v2 and FHIR standards.

This map connects vaccine-preventable diseases (identified by SNOMED codes) to the vaccines that target them (identified by CVX codes). This mapping facilitates searching ImmSOT using the targetDisease search parameter.

This map connects vaccine products as identified by the Therapeutic Product Unit of Use (TPUU) code in the New Zealand Medicines Terminology (NZMT) to the vaccines as identified by CVX codes. This mapping facilitates translating TPUU codes stored in ImmSOT to a CVX code that can be received by legacy PMS systems.

This maps the gender codes listed in the NIR Message Spec v4.5, Sep 2020 (HL7 Table 0001) to the codes returned by the NHI Service.

This maps HL7 Immunization Function Codes and Provider Roles to AIR Health Worker Function Codes. HL7v2 codes are from V2 table 0443 (Provider Role) and map to message segments as defined in CodeSystem: providerRole. HL7v3 codes are from CodeSystem: ParticipationType

This maps the AIR Route of Administration from HL7v2 messaging to SNOMED CT NZ.

This maps the vaccination site codes listed in the NIR Message Spec v4.5, Sep 2020 (HL7 Table 0162) to SNOMED CT NZ.

This is an example of a how multiple immunisation records will be returned from ImmSoT, inclusive of and following the expansion functions performed by the Orchestration Service.

A simple example of the immunization resource, to be used as a starting point in learning, testing, and building more complex examples. This has the absolute minimum amount of data.

An example immunization resource containing the complete set of fields for recording an immunisation event in AIR.

This example immunization fails FHIR validation because it has a reschedule date but the status is 'completed'. If a reschedule date is provided, the status must be set to 'not-done' and the statusReason code must be either 'RESCHO', 'RESREF', or 'RESTC'.

An example of the immunization resource, including the planned event match quality extension.

An example of the immunization resource, including the planned event match quality extension.

An AIR ImmunizationRecommendation showing scheduled events for a patient.

Example immunisation update request message

Example immunisation update request message

Example immunisation update response with meta.tag

Example synchronous response from Orchestration Server to an update-immunisation request message

Example synchronous response from Orchestration Server to an update-immunisation request message

Example immunisation nomination response message