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

General Notes

Resource representation: Json

Only JSON is supported by this implementation.

Id and Identifiers

Immunization resources in this implementation are uniquely identified by their id, which is the ‘physical’ identity of the resource. Retrieving the Immunization resource can be done in two ways.

Read Resource by Id

GET https://api_endpoint/Immunization/{id} with parameters

For further information see the Read Immunisation Event item under the Use Cases menu.

Search Immunisation Events

POST https://api_endpoint/Immunization/_search with parameters

For more information see the Search Immunisation Events item under the Use Cases menu.

Additional search parameters

target-disease

Restricts results to specific target disease(s) by system|code, for example: "http://snomed.info/sct|123456,http://loinc.org|7890". Exact matching is applied with no mapping of concepts between code systems.

status-reason:not-in and status:not-in

These exclude given status_reason(s) and status(es), enabling consuming applications to present relevant results only. For example, a user might not want to be distracted by closed and deleted records. See the Open API specification for further detail on these parameters.

Enrichment: the _include parameter

Certain operations allow for enrichment of the response bundle with referenced Patient, Location, Organization and Practitioner resources. If those resources are to be accessed, then onboarding to NHI and HPI is required.

Count and Offset in DQ results

For those with permission to view Data Quality (DQ) results, the AIR APIs default to returning 100 results in the search bundle e.g. GET<endpoint>/Immunization/_search?_query=data-quality will return the first 100 rows.

To receive more than 100, and for paginated searching, use parameters _count and _offset.

• _count - This search parameter is used to extend the search and has a limit of 50 search results.
• _offset - This search parameter is used to get the next set of search results

Example usage:

• First request - GET/Immunization/_search?_query=data-quality&_count=50
• Second request - GET/Immunization/_search?_query=data-quality&_count=50&_offset=50
• Third request - GET/Immunization/_search?_query=data-quality&_count=50&_offset=100

dateTime support and UTC default

The FHIR dateTime data type is defined as:

A date, date-time or partial date (e.g. just year or year + month) as used in human communication. The format is YYYY, YYYY-MM, YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+zz:zz

AIR APIs do not support partial dates (YYYY, YYYY-MM) in Create/Update interactions. dateTime values received by AIR with Day precision are preserved with Day precision on output (no time zone).

If hours and minutes are provided in datetime values, the FHIR dateTime type requires time zone. While AIR accepts values with no time zone, UTC is the default.

dateTime values with a time component are output in UTC with +00:00 offset. Applications are responsible for localising dateTime values when displaying dates and times to users or grouping at Day level.

Live and Dormant NHI Numbers

Sometimes a person may have been added more than once to the NHI and been accidentally assigned more than one NHI number. When this is discovered, the NHI records are linked. One of the NHI numbers becomes the ‘live’ identifier and the other NHI numbers become ‘dormant’ identifiers.

AIR retains the submitted NHI number on immunisation records.

• API Subscribers SHALL expect that AIR will include in search API responses and NEMS notifications records for all NHIs currently linked to the consumer, including live and dormant NHIs.
• When a NHI is moved to another patient then immunisation records associated with that NHI SHALL become associated with that patient.
• Update requests SHALL NOT be used to update the immunisation record NHI number.
• The NHI returned in the response body to an Upsert request SHALL be used as the authoritative value for the record. They shall not assume that the NHI submitted in the request was stored. The meta tag patient-identifier-immutable is returned in the scenario where the NHI returned differs from that submitted.

For further information about Live and Dormant identifiers refer to the New Zealand NHI IG.

Dose 0 and null dose number

In this implementation doseNumberString is used in protocolApplied and recommendation elements. This SHALL be an integer between 0 and 97, or empty.

External applications commonly record zero (0) to represent an ‘early’ dose where clinically recommended. Nulls appear in data migrated to AIR from systems that did not record dose number.

For historical reasons, values 98 and 99 are reserved.

Health Worker Identifiers

The AIR requires health workers administering immunisations to be authorised. Records must be kept for traceability and legal reasons. Therefore, function (role) and identifier are important.

The HPI number (HPI Common Person Number CPN) is the preferred identifier. If a registration number is used, it should relate to administering immunisations.

The vaccinating workforce is diverse and many health workers do not have a CPN or relevant registration. Often this applies to health care assistants, kaiāwhina hauora and Vaccinating Health Workers.

AIR accepts a broad range of Practitioner identifiers, including some specific to AIR. AIR also provides for the use case where the only available identifier is local to the site or organisation:

• Immunization performer function (role in the encounter) SHOULD be consistent with the Registration Authority of the Health Worker. This informs vaccinating workforce reporting.
• AIR Performer Health Worker Function Code value set includes a hierarchy of AIR Terms, with parent AP and OP codes equivalent to base ImmunizationFunctionCodes.
• Each immunisation event SHOULD have at least one health worker with function AP or a child thereof.
  • If a Vaccinating Health Worker (VHW registration type) administers an immunisation, the function SHOULD be VHW. Vaccinating Health Worker identifiers are assigned in the AIR Portal.
  • If a registered nurse, doctor, midwife, paramedic or pharmacist administers an immunisation, the function SHOULD be VC.
  • When a student or trainee administers a dose with a supervisor or instructor present, their roles SHOULD be recorded with function codes PPRF and ATND respectively.
• An Ordering Provider (function OP) and Data Entry Person (function ENT) MAY be provided.
• If a health worker authorised to administer immunisations has no registration or CPN, their identifier MUST be unique within the source system and SHOULD have system 'https://HCA'. The identifier must be traceable to an individual health worker.
• Request-Context header and CreatedBy and ModifiedBy meta fields capture usernames of those who interact with the record, such as someone recording on behalf of the responsible provider.
• Request-Context header field secondaryIdentifier MUST be the end user’s CPN where available. Otherwise, any secondary identifier that is held for the user. This value is mandatory and must be correct and accurate, due to legal requirements. If the person triggering the request is not registered with any New Zealand health body on the list provided at standards.digital.health.nz, the value must remain empty (empty string).
• The mapping between AIR Registration Authority URLs and legacy HL7v2 AIR Registration Type codes is available from the HNZ Terminology Service.

Immunization status and statusReason

Immunisation status and statusReason SHOULD correspond, according to the table below. Events not complying with this rule are not able to be categorised, reported or matched to a planned event. This table is available from the NZHTS as a Concept Map: AIR Immunization Status < – > AIR Status Reason.

Scenario	Immunization.status	Immunization.statusReason	Business Rules
Immunisation given in NZ	completed	null or GIVEN	Body Site, Route, Vaccine lot number and Vaccine Expiration Date SHOULD have a value when statusReason = "GIVEN" or is null
Declined (permanent contraindication)	not-done	DMC
Declined by parent/guardian	not-done	DPC
Declined by individual	not-done	DIC
Immune	not-done	DNI	Marks the matching planned event as not required. Serology report SHOULD be contained.
Closed not required	not-done	CPI	For HNZ internal use only. Marks the matching planned event as not required. No notification is sent to providers.
Alternative vaccination given	completed	ALTGIVN	This record identifies the vaccine replaced by an alternative, relevant only to NIS events. Deprecated, retained for backward compatibility.
Given overseas	completed	GIVNOS	Immunisation not given in NZ. Lot numbers and expiry dates, route and site are optional.
Historic vaccination	completed	HSTGIVN	Immunisation given in NZ prior to 2005 or was not recorded in NIR prior to December 2023, for which complete details are not available SHOULD have statusReason="HSTGIVN". Lot numbers and expiry dates, route and body site are optional.
Deleted, invalidated, duplicate of a good record	entered-in-error	any	Does not match any planned event. Most fields are optional but should preserve any previous values.

Rescheduling of events is not supported (status reason codes RESCHO, RESREF, RESTC).

Typical PMS status query (_search request) parameters are status-reason:not-in=CPI,RESCHO,RESREF,RESTC&status:not-in=entered-in-error

Planned and Expected Events

Planned events based on a consumer’s schedule are represented in ImmunizationRecommendation resources. These contain a recommendation node for each Consumer Planned Event (type CPE), with a related recommendation of type Expected Event (EE) when the date is moved due to dose gap or other scheduling rules. Past recommendations can be due or overdue. Events marked as not required do not appear in the consumer’s schedule.

Appointments and rescheduled events are not recorded in the AIR.

In future, a consumer’s CarePlan resources will present Immunization and ImmunizationRecommendation together for each antigen group, where matching.

Errors

System failures and rejection responses

Errors fall into several categories that depend on the issue and request type.

• Immunisation Event Rejection Rules are found in Rejection Rules.
• HTTP status codes identify common technical faults and conditions. These are documented in the Open API Specification associated with this implementation guide. OperationOutcome diagnostics in the response contain human-readable descriptions depending on context.
• FHIR profile faults are mostly caught in the HAPI library, with diagnostics like “HAPI-nnnn: …”
• FHIR constraint violations usually repeat the text of the constraint rule in diagnostics.
• Well-formed requests can fail due to invalid values or business rule violations. In such cases the diagnostics describe the problem to be resolved.
• Refer to the Use Cases pages for example responses.

Data quality issue detection and remediation

The AIR applies further checks on data quality (DQ) as specified in Data Quality Rules. These include possible and exact duplicates, deviations from ‘preferred’ value sets, inconsistent dates, data missing that should be provided under specific conditions, etc.

Immunisation events containing issues cause DQ cases to be raised for follow-up by the AIR support team. DQ cases are closed automatically when underlying issues are resolved.

Each deviation is ranked and a score is calculated. Authorised applications receive DQ details in the air-data-quality-assessment extension in responses to Create & Update interactions and the Immunization/_search operation.

Duplicates

The PMS system shall correctly handle AIR outcomes in the following scenarios:

• If an exact duplicate is detected in AIR during creation or upsert, AIR will return the record that survived duplicate resolution with meta tag "exact-duplicate-not-created". The PMS must handle scenarios where it already has this AIR Identifier on another record held locally.
• If an exact duplicate is detected in AIR during update, the update will return the status in AIR of the target (updated) record, which will be entered-in-error with Status Reason SNOMED 445672005. This shall be reflected in the local record. In this scenario, AIR will emit a Duplicate Resolution event via NEMS that cites the AIR Identifiers for both events.
• Another scenario exists, where a potential duplicate is detected. In such cases, the immunisation event will be created or updated successfully and flagged in the AIR for administrative review while the status is kept as submitted. The PMS system is not expected to perform any action on this record during the create or update processes.
• Administrative review of potential duplicates usually results in one record being kept. When this occurs, AIR will emit a Duplicate Resolution event via NEMS. An Update event (setting status to entered-in-error) is not emitted in this scenario.
• When administrative review decides to keep both records with no other changes, the change of Data Quality status does not cause an Update event to be emitted via NEMS (other edits would emit an Update event). The potential duplicate will then have meta.extension:air-data-quality-assessment.extension:dqStatus="A" (Accepted).

HTTP Header Details

Request Headers

The AIR external APIs comply with Health New Zealand | Te Whatu Ora API Standards. In particular Part C: Synchronous APIs: HTTP Headers specifies headers that are expected in requests to AIR.

Notes:

• Some custom X- notation headers are FHIR standard, but such headers have been deprecated by HNZ. Those headers might change in future.
• Only JSON is supported by this implementation and the application must provide Content-Type: application/jsonand Accept: application/json,version=\*

API Interactions and Operations

Category	Verb	Endpoint	External	Internal	Notes
Consumer	GET	/Patient/{NHI}	N	Y	Returns information about the state of the consumer.
Consumer	POST	/Patient/{NHI}/$update-state	N	Y	Edits the consumer state information.
Consumer	GET	/Patient/{NHI}/_history	N	Y	Returns all versions of an ImmSOT Consumer including modification information.
Immunisation	GET	/Immunization/_search	Y	Y	Returns a list of immunisations the consumer has had
Immunisation	GET	/Immunization/{ID}/_history	N	Y	Returns all versions of this immunisation event
Immunisation	GET	/Immunization/{ID}	Y	Y	Returns latest version of this immunisation event only
Immunisation	POST	/Immunization	Y	Y	Records a new immunisation event
Immunisation	PUT	/Immunization/{ID}	Y	Y	Edits an existing immunisation event
Immunisation	POST	/Immunization/$upsert	Y	Y	Create-or-update - performs a conditional update if the the record provided maps to one and only one existing record in the AIR, otherwise records a new immunisation event
Immunisation	POST	/Immunization/$process-message	HealthLink broker only	Y	Updates an existing acknowledgement from SENT to RECEIVED status. Supports co-existence with HL7 v2 messaging.
Immunisation	POST	/Immunization/$bulk-update	HealthLink broker only	Y	Create new immunisation events and/or Upsert immunisation events based on a matching algorithm. Operation is atomic. Supports co-existence with HL7 v2 messaging.
Consumer Schedule	POST	/Immunization/{ID}/$match	N	Y	Matches an immunisation event to a planned event
Consumer Schedule	POST	/Immunization/{ID}/$unmatch	N	Y	Unmatches an immunisation event from a planned event
Consumer Schedule	POST	/Patient/{NHI}/$reassign-schedules	N	Y	Updates the immunisation plan of an ImmSOT Consumer by reassessing and reassigning their schedules.
Consumer Schedule	GET	/ImmunizationRecommendation/$view	N	Y	Returns the planned events for the consumer
Consumer Schedule	GET	/CarePlan/$view	N	Test only	Returns the planned events for the consumer