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)
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
The "create" operation is used to create a new immunisation event. This method performs validation checks to ensure that the event is valid before it is created.
The create operation performs the following:
entered-in-error and status reason to 'Duplicate report'. For further information, see Handling of Exact Duplicates.POST https://api_endpoint/Immunization
All headers listed in Request Headers.
Post a full set of immunisation record details. See below. The FHIR specification for an AIR Immunization resource is at AIR Immunization Profile.
{
"resourceType": "Immunization",
"patient": {
"identifier": [
{
"system": "https://standards.digital.health.nz/ns/nhi-id",
"value": "ZZZ7541"
}
]
},
"occurrenceDateTime": "2023-08-29",
"vaccineCode": {
"text": "Priorix",
"coding": [
{
"system": "http://hl7.org/fhir/sid/cvx",
"code": "03",
"version": "1.0.0"
}
]
},
"protocolApplied": [
{
"doseNumberPositiveInt": 1
}
],
"lotNumber": "555123",
"expirationDate": "2024-01-31",
"contained": [
{
"resourceType": "RelatedPerson",
"id": "1",
"patient": {
"identifier": {
"system": "https://standards.digital.health.nz/ns/nhi-id",
"value": "ZZZ7541"
}
},
"relationship": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
"code": "FTH"
}
]
}
],
"name": [
{
"family": "Doe",
"given": [
"John",
"Jon"
]
}
],
"telecom": [
{
"system": "phone",
"value": "041234567",
"use": "home"
},
{
"system": "phone",
"value": "091234567",
"use": "work"
},
{
"system": "email",
"value": "jodoe@moh.govt.nz",
"use": "home"
}
],
"address": [
{
"extension": [
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/suburb",
"valueString": "Johnsonville"
}
],
"use": "home",
"type": "physical",
"line": [
"123 Main St",
"Neverland"
],
"city": "Wellington",
"postalCode": "6001"
}
]
},
{
"resourceType": "Observation",
"id": "2",
"meta": {
"profile": [
"https://standards.digital.health.nz/fhir/air/StructureDefinition/air-serology-report-profile"
]
},
"status": "preliminary",
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "278969009"
}
]
},
"interpretation": [
{
"coding": [
{
"system": "https://standards.digital.health.nz/ns/air-serology-protection-terms",
"code": "IND"
}
]
}
],
"effectiveDateTime": "2023-01-01T13:12:34+12:00"
}
],
"extension": [
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-diluent",
"extension": [
{
"url": "diluentLotNumber",
"valueString": "33332222"
},
{
"url": "diluentExpiryDate",
"valueDate": "2026-01-01"
}
]
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-related-person-extension",
"valueReference": {
"reference": "#1"
}
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-mobile-site",
"valueString": "FZZ835-E_MOB0001"
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-serology-report-extension",
"valueReference": {
"reference": "#2"
}
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-administered-product",
"valueCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "10443641000116108"
}
],
"text": "M-M-R-II"
}
}
],
"route": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "78421000",
"version": "1.2"
}
]
},
"site": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "16217701000119102",
"version": "1.1"
}
]
},
"location": {
"identifier": {
"system": "https://standards.digital.health.nz/ns/hpi-facility-id",
"value": "FZZ835-E"
}
},
"status": "completed",
"statusReason": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/air-status-reason-terms",
"code": "GIVEN"
}
]
},
"reasonCode": [
{
"coding": [
{
"system": "https://standards.digital.health.nz/ns/air-terms-code",
"code": "Stn"
}
]
}
],
"performer": [
{
"actor": {
"identifier": {
"system": "https://standards.digital.health.nz/ns/nursing-council-id",
"value": "477616"
}
},
"function": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/air-terms-code",
"code": "VC",
"version": "1.0.0"
}
]
}
}
]
}
With the Patient Identifier for the incoming event, AIR compares to all existing events for that Patient. If an exact match is found, then it creates a new record, however:
The API Client must anticipate and handle this condition.
The API returns the created Immunization record if successfully created. If any issues arose with the create, the response will contain an OperationOutcome resource array. The OperationOutcome resource indicates that the create operation failed, with an issue array providing details with severity and code values.
{
"resourceType": "Immunization",
"id": "bb14c00e-83b7-494b-98aa-6b9295d2ea3a",
"meta": {
"extension": [
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-created-source-system",
"valueString": "Postman"
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-created-by",
"valueString": "PostmanUser"
},
{
"url": "http://hl7.org/fhir/StructureDefinition/firstCreated",
"valueInstant": "2023-09-14T01:32:28.986+00:00"
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-modified-by",
"valueString": "PostmanUser"
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-modified-source-system",
"valueString": "Postman"
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-data-quality-assessment",
"extension": [
{
"url": "dqScore",
"valueInteger": 84
},
{
"url": "dqLastUpdated",
"valueDateTime": "2023-09-14T01:32:29.038+00:00"
},
{
"url": "dqStatus",
"valueString": "I"
},
{
"url": "DQViolations",
"extension": [
{
"url": "DQViolation",
"extension": [
{
"url": "violationCode",
"valueString": "430"
},
{
"url": "violationType",
"valueString": "DataQuality"
},
{
"url": "violationMessage",
"valueString": "One or more health worker is unrecognised. An immunisation event should have a health worker identification number that passes the checksum criteria when the system is https://standards.digital.health.nz/ns/hpi-person-id, or it should have a health worker identification number and the system https://standards.digital.health.nz/ns/air-vhw-id or https://standards.digital.health.nz/ns/medical-council-id or https://standards.digital.health.nz/ns/nursing-council-id or https://standards.digital.health.nz/ns/air-cir-id or https://standards.digital.health.nz/ns/pharmacy-council-id or https://standards.digital.health.nz/ns/paramedic-council-id or https://standards.digital.health.nz/ns/midwifery-council-id or https://HCA."
},
{
"url": "violationElement",
"valueString": "Immunization.performer[0].actor"
},
{
"url": "violationWeighting",
"valueInteger": 2
}
]
},
{
"url": "DQViolation",
"extension": [
{
"url": "violationCode",
"valueString": "150"
},
{
"url": "violationType",
"valueString": "DataQuality"
},
{
"url": "violationMessage",
"valueString": "One or more indication code is unrecognised. An indication code should be part of the air-indication-code value set."
},
{
"url": "violationElement",
"valueString": "Immunization.reasonCode[0]"
},
{
"url": "violationWeighting",
"valueInteger": 2
}
]
}
]
}
]
}
],
"versionId": "1",
"lastUpdated": "2023-09-14T01:32:28.986+00:00",
"profile": [
"https://standards.digital.health.nz/fhir/air/StructureDefinition/air-immunization"
]
},
"contained": [
{
"resourceType": "RelatedPerson",
"id": "1",
"patient": {
"reference": "https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZZZ7541",
"identifier": {
"system": "https://standards.digital.health.nz/ns/nhi-id",
"value": "ZZZ7541"
}
},
"relationship": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
"code": "FTH"
}
]
}
],
"name": [
{
"family": "Doe",
"given": [
"John Jon"
]
}
],
"telecom": [
{
"system": "phone",
"value": "041234567",
"use": "home"
},
{
"system": "phone",
"value": "091234567",
"use": "work"
},
{
"system": "email",
"value": "jodoe@moh.govt.nz",
"use": "home"
}
],
"address": [
{
"extension": [
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/suburb",
"valueString": "Johnsonville"
}
],
"use": "home",
"type": "physical",
"line": [
"123 Main St",
"Neverland"
],
"city": "Wellington",
"postalCode": "6001"
}
]
},
{
"resourceType": "Observation",
"id": "2",
"status": "preliminary",
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "278969009",
"display": "Hepatitis B status"
}
]
},
"effectiveDateTime": "2023-01-01T01:12:34.000+00:00",
"interpretation": [
{
"coding": [
{
"system": "https://standards.digital.health.nz/ns/air-serology-protection-terms",
"code": "IND"
}
]
}
]
}
],
"extension": [
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-diluent",
"extension": [
{
"url": "diluentLotNumber",
"valueString": "33332222"
},
{
"url": "diluentExpiryDate",
"valueDate": "2026-01-01"
}
]
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-related-person-extension",
"valueReference": {
"reference": "#1"
}
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-age-given",
"extension": [
{
"url": "years",
"valueInteger": 24
},
{
"url": "months",
"valueInteger": 6
},
{
"url": "days",
"valueInteger": 27
},
{
"url": "daysSinceBirth",
"valueInteger": 8974
},
{
"url": "precision",
"valueString": "DAY"
}
]
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-mobile-site",
"valueString": "FZZ835-E_MOB0001"
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-serology-report-extension",
"valueReference": {
"reference": "#2"
}
},
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-administered-product",
"valueCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "10443641000116108",
"display": "M-M-R-II"
}
],
"text": "M-M-R-II"
}
}
],
"status": "completed",
"statusReason": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "127785005",
"display": "Administration of substance to produce immunity, either active or passive"
}
]
},
"vaccineCode": {
"coding": [
{
"system": "http://hl7.org/fhir/sid/cvx",
"version": "1.0.0",
"code": "03",
"display": "MMR"
}
],
"text": "Priorix"
},
"patient": {
"reference": "https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZZZ7541",
"identifier": {
"system": "https://standards.digital.health.nz/ns/nhi-id",
"value": "ZZZ7541"
}
},
"occurrenceDateTime": "2023-08-29T00:00:00.000+00:00",
"location": {
"reference": "https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ835-E",
"identifier": {
"system": "https://standards.digital.health.nz/ns/hpi-facility-id",
"value": "FZZ835-E"
}
},
"lotNumber": "555123",
"expirationDate": "2024-01-31",
"site": {
"coding": [
{
"system": "http://snomed.info/sct",
"version": "1.1",
"code": "16217701000119102",
"display": "Structure of left deltoid muscle"
}
]
},
"route": {
"coding": [
{
"system": "http://snomed.info/sct",
"version": "1.2",
"code": "78421000",
"display": "Intramuscular route"
}
]
},
"performer": [
{
"function": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/air-terms-code",
"version": "1.0.0",
"code": "VC",
"display": "Vaccinator"
}
]
},
"actor": {
"reference": "https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/477616",
"identifier": {
"system": "https://standards.digital.health.nz/ns/nursing-council-id",
"value": "477616"
}
}
}
],
"reasonCode": [
{
"coding": [
{
"system": "http://snomed.info",
"code": "359953009"
}
]
},
{
"coding": [
{
"system": "http://snomed.info",
"version": "1",
"code": "359953009"
}
]
}
],
"protocolApplied": [
{
"doseNumberPositiveInt": 1,
"targetDisease": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "14189004",
"display": "Measles"
}
]
},
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "36989005",
"display": "Mumps"
}
]
},
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "36653000",
"display": "Rubella"
}
]
}
]
}
]
}
The DQ taken from the DQViolations section
{
"url": "DQViolation",
"extension": [
{
"url": "violationCode",
"valueString": "520"
},
{
"url": "violationType",
"valueString": "DataQuality"
},
{
"url": "violationMessage",
"valueString": "An immunisation event should have a diluent expiry date, and the diluent expiry date should not be before the immunisation event date."
},
{
"url": "violationElement",
"valueString": "Immunization.extension.where(url='https://standards.digital.health.nz/fhir/air/StructureDefinition/air-diluent').extension.where(url='diluentExpiryDate').valueDate"
},
{
"url": "violationWeighting",
"valueInteger": 1
}
]
}
{
"url": "DQViolation",
"extension": [
{
"url": "violationCode",
"valueString": "310"
},
{
"url": "violationType",
"valueString": "DataQuality"
},
{
"url": "violationMessage",
"valueString": "The body site code is unrecognised. A body site code should be part of the air-site-code value set."
},
{
"url": "violationElement",
"valueString": "Immunization.site"
},
{
"url": "violationWeighting",
"valueInteger": 1
}
]
}
{
"url": "DQViolation",
"extension": [
{
"url": "violationCode",
"valueString": "430"
},
{
"url": "violationType",
"valueString": "DataQuality"
},
{
"url": "violationMessage",
"valueString": "One or more health worker is unrecognised. An immunisation event should have a health worker identification number that passes the checksum criteria when the system is https://standards.digital.health.nz/ns/hpi-person-id, or it should have a health worker identification number and the system https://standards.digital.health.nz/ns/air-vhw-id or https://standards.digital.health.nz/ns/medical-council-id or https://standards.digital.health.nz/ns/nursing-council-id or https://standards.digital.health.nz/ns/air-cir-id or https://standards.digital.health.nz/ns/pharmacy-council-id or https://standards.digital.health.nz/ns/paramedic-council-id or https://standards.digital.health.nz/ns/midwifery-council-id or https://HCA."
},
{
"url": "violationElement",
"valueString": "Immunization.performer[0].actor"
},
{
"url": "violationWeighting",
"valueInteger": 2
}
]
}
{
"url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-data-quality-assessment",
"extension": [
{
"url": "dqScore",
"valueInteger": 100
},
{
"url": "dqLastUpdated",
"valueDateTime": "2026-04-06T21:24:17.294+00:00"
},
{
"url": "dqStatus",
"valueString": "I"
},
{
"url": "DQViolations",
"extension": [
{
"url": "DQViolation",
"extension": [
{
"url": "violationCode",
"valueString": "800"
},
{
"url": "violationType",
"valueString": "duplicate"
},
{
"url": "violationWeighting",
"valueInteger": 0
},
{
"url": "violationMessage",
"valueString": "This Immunization resource has been identified as a duplicate of existing Immunization resources"
},
{
"url": "violationElement",
"valueString": "Immunization.where(id in 'c8a8b99f-f325-4fac-a90b-2e462744c19c')"
}
]
}]
}
]
}
Where the data provided causes a hard failure, an example being user resolvable, where the lot number exceeds the field length The http result will be 422 and the payload is an operation outcome error message.
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "invariant",
"diagnostics": "Vaccine lot number cannot be greater than 50 characters"
}
]
}
Any FHIR scope that includes system/immunization.c , for example system/immunization.cruds and/or system/immunization.c
{
"system": "https://standards.digital.health.nz/ns/hpi-facility-id",
"value": "FZZ958-K"
}
Then the "reference" should be "https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ958-K"
A full example for a location payload is below.
"location": {
"reference": "https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ958-K",
"identifier": {
"system": "https://standards.digital.health.nz/ns/hpi-facility-id",
"value": "FZZ958-K"
}
},
The operation may return data quality violations based on the Data Quality Rules
The record can also be identified by ImmSOT as duplicate; see the details of this here.