AIR Integration | RebateRight

What is the AIR?

The Australian Immunisation Register (AIR) is a national register that records all vaccinations given to individuals of all ages living in Australia. This includes people who are not eligible for Medicare, such as newborns, newly arrived immigrants and student visa holders.

RebateRight & AIR

RebateRight sends your AIR requests to Services Australia under RebateRight’s Notice of Integration, with the PRODA authentication Services Australia requires. Request and response bodies follow AIR’s own shapes.

Before your first AIR request

Each vaccination location needs 3 things in place:

A recognised vaccination provider. A medical practitioner, midwife or nurse practitioner with a Medicare provider number is recognised automatically. Any other provider, such as a council or a pharmacy, applies for recognition with Services Australia’s IM004 form and receives an AIR provider number.
The HW027 form, with the location’s Minor ID. The HW027 form is needed before the first AIR request, including at a clinic that records vaccinations but does not claim through RebateRight. The Minor ID page explains how to get the Minor ID and submit the form.
A provider number that matches the Minor ID. AIR checks the Minor ID in x-minor-id against the information provider number on every request. AIR returns AIR-E-1039 when the provider number is not linked to that Minor ID. AIR returns AIR-E-1063 when it has not authorised the provider for the service requested.

Response envelope

When AIR answers, its JSON response carries these fields beside the endpoint’s own data:

Field	Description
`statusCode`	AIR message code for the overall outcome. See Status codes.
`codeType`	Code-type category: `AIRIBU` for information, `AIRWBU` for a warning and `AIREBU` for an error.
`message`	Status message from AIR.
`errors`	Field-level validation problems. Present only when `statusCode` is `AIR-E-1005`. See Validation codes.
`correlationId`	Unique request identifier in the format `urn:uuid:{MinorId}{16 hex chars}`. Include it in any support request so we can trace the request.

Pre-flight errors

When the request body has a structural fault, such as invalid JSON, a missing top-level required field or a field of the wrong type, the response uses a separate envelope. It carries codeType: DHSEIN in place of statusCode and errors[]:

Field	Description
`code`	Numeric pre-flight error code, such as `5`.
`codeType`	Always `DHSEIN` for pre-flight errors.
`message`	Plain-language description of the fault in the request.
`correlationId`	Unique request identifier in the same format as the AIR envelope.

Common messages:

Message	Cause
`Invalid object: the property '<field>' is missing.`	A top-level required field is absent.
`Invalid value type '<type>'.`	A field has the wrong JSON type.
`Invalid null syntax`	The request body is not valid JSON.

Pre-flight errors come from Services Australia’s gateway, which checks the request’s structure before AIR applies its business rules. RebateRight passes them through unchanged. AIR’s own validation errors use the standard envelope with statusCode: AIR-E-1005 instead.

Responses from RebateRight

RebateRight answers some requests itself, in plain text: a 400 for a missing body or Minor ID, a 401 for a missing or invalid API Key and a 503 when it cannot complete the request. Troubleshooting gives the cause and the fix for each.

When Services Australia returns a body that is not JSON, such as a 404 for an unknown path, RebateRight keeps Services Australia’s HTTP status and returns a JSON body. That body sets invalidResponseFromServicesAustralia to true, holds the raw text in body and carries the correlationId.

Status codes

AIR uses a three-tier prefix:

Prefix	Meaning
`AIR-I-*`	Informational: request succeeded
`AIR-W-*`	Warning: request processed, with an outcome to review
`AIR-E-*`	Error: request failed validation or processing

The response envelope carries codes in 2 places:

statusCode. The top-level outcome for the request.
errors[].code. Field-level validation problems, present only when statusCode is AIR-E-1005.

AIR returns its outcomes, including validation errors, as HTTP 200 with a statusCode. Gateway errors and RebateRight’s own responses carry no statusCode. Read the HTTP status first, then read statusCode on an HTTP 200 response.

Display message and errors[].message exactly as AIR returns them. Services Australia requires unchanged wording.

Top-level `statusCode` values

AIR returns one of these codes in statusCode for the overall outcome of each request.

Code	Meaning
`AIR-I-1007`	All encounter(s) were successfully recorded.
`AIR-I-1009`	Catch-up date was successfully recorded.
`AIR-I-1100`	Request was successfully processed.
`AIR-W-0033`	Vaccine and/or dose number administered not supplied.
`AIR-W-0044`	Vaccine not valid for encounter date.
`AIR-W-1004`	Individual was not found. Correct the details or confirm and accept them as-is.
`AIR-W-1008`	Some encounter(s) were not successfully recorded. Correct the details or submit confirmation accepting episode status.
`AIR-W-1010`	Catch-up date already exists for the individual.
`AIR-W-1011`	Catch-up date period has expired.
`AIR-W-1059`	Immunisation details cannot be viewed at this time. Recording new encounters is still allowed.
`AIR-W-1062`	Some fields in this record may not be available for updating. Recording new encounters is still allowed.
`AIR-E-1005`	Request contained validation errors. See `errors[]`.
`AIR-E-1006`	Unexpected error. Retry shortly. If the error persists, send us the `correlationId`.
`AIR-E-1046`	Some encounter(s) were not recorded. Correct the details and resubmit, or remove the invalid encounters.
`AIR-E-1058`	Individual’s record cannot be viewed or updated at this time.
`AIR-E-1067`	Action cannot be performed against the individual’s record. Services Australia documents this code both as a `statusCode` and in `errors[]`, so handle it in either place.
`AIR-E-1078`	Immunisation history statement cannot be generated or viewed at this time.

Validation codes

AIR returns these codes in errors[] when statusCode is AIR-E-1005. Each entry has code, field and message, and message carries Services Australia’s full text. The table below summarises each code so you can match it during integration.

Code	Meaning
`AIR-E-1013`	Maximum number of encounters exceeded.
`AIR-E-1014`	Episode sequencing error. Sequence numbers must begin with 1 and increment by one.
`AIR-E-1015`	Date of Service must be after the individual’s Date of Birth.
`AIR-E-1016`	Invalid format for the supplied field value.
`AIR-E-1017`	Invalid value: not one of the permitted values, or failed a check-digit check.
`AIR-E-1018`	Date field is in the future.
`AIR-E-1019`	Date field is more than 130 years in the past.
`AIR-E-1020`	Medicare card number must be supplied when IRN is set.
`AIR-E-1021`	Immunising Provider Number must be supplied.
`AIR-E-1022`	Date of Service is invalid.
`AIR-E-1023`	Vaccine code is invalid.
`AIR-E-1024`	Vaccine dose is invalid.
`AIR-E-1025`	Encounter has more than one episode with an equivalent vaccine.
`AIR-E-1026`	Individual information provided is insufficient.
`AIR-E-1027`	School ID is invalid.
`AIR-E-1028`	Immunisation Provider number must exist on AIR and be current. Services Australia’s documents differ on whether it must be current at the date of service or at the date of submission.
`AIR-E-1029`	Information Provider number must exist on AIR and be current at submission.
`AIR-E-1030`	Confirmation flag is set but the individual has already been matched.
`AIR-E-1031`	Confirmation flag is set but Medicare Card or IHI details have been provided.
`AIR-E-1033`	Claim ID must be set on confirmation requests.
`AIR-E-1034`	Claim sequence must be set when Claim ID is set.
`AIR-E-1035`	Individual not found.
`AIR-E-1036`	Postcode and Locality combination must be valid.
`AIR-E-1037`	Address line two can only be set when address line one is provided.
`AIR-E-1038`	Customer ID must be a valid format.
`AIR-E-1039`	Minor ID is not authorised to perform this action for the supplied Information Provider.
`AIR-E-1040`	Claim ID must not be set unless this is a confirmation request.
`AIR-E-1041`	Encounter sequencing error. Sequence numbers must begin with 1 and increment by one.
`AIR-E-1042`	New-individual confirmation requires first name (or `onlyNameIndicator`), last name, date of birth, gender, address line one, locality, and postcode.
`AIR-E-1043`	Postcode is not valid.
`AIR-E-1044`	Individual’s AIR registration is not current at the date of service, or cannot be viewed or updated.
`AIR-E-1047`	Catch-up date cannot be generated for individuals over 20 years.
`AIR-E-1048`	Medical contraindication reason is invalid for this vaccine.
`AIR-E-1049`	A natural immunity for this disease has been previously recorded.
`AIR-E-1050`	End date is before start date.
`AIR-E-1051`	End date is required for temporary type, or is earlier than the start date.
`AIR-E-1052`	Encounter cannot be found.
`AIR-E-1055`	Submission date is invalid.
`AIR-E-1056`	Date of Service is greater than the receipt date.
`AIR-E-1061`	Individual Identifier is invalid or has expired.
`AIR-E-1063`	Information provider is not authorised to use this service.
`AIR-E-1064`	Details are invalid, or not authorised to update this encounter.
`AIR-E-1065`	Acknowledgement field must be selected to change the Additional Vaccines Required indicator.
`AIR-E-1066`	Supplied field value is in the past or incorrect.
`AIR-E-1067`	Action cannot be performed against the individual’s record.
`AIR-E-1068`	Antigen code is invalid.
`AIR-E-1069`	One of 2 required fields must be supplied.
`AIR-E-1070`	Immunisation provider details should not be supplied for encounters administered overseas.
`AIR-E-1079`	Country/Region code is required when `administeredOverseas` is `true`.
`AIR-E-1080`	Country/Region code should not be supplied unless administered overseas.
`AIR-E-1081`	Batch number is mandatory for the supplied vaccine.
`AIR-E-1082`	Field should not be supplied when the conflicting field is `true`.
`AIR-E-1083`	A medical contraindication for this disease has been previously recorded.
`AIR-E-1084`	Invalid code for Vaccine Type.
`AIR-E-1085`	Invalid code for Route of Administration.
`AIR-E-1086`	Vaccine Funding Type and Vaccine Code are not compatible.
`AIR-E-1087`	Route of Administration and Vaccine Code are not compatible.
`AIR-E-1088`	Field is mandatory for the supplied vaccine.
`AIR-E-1089`	Antenatal indicator is mandatory for this encounter.
`AIR-E-1090`	Vaccine brand is required if you performed this immunisation encounter.
`AIR-E-1091`	This vaccine is only accepted when the encounter was performed overseas.
`AIR-W-1012`	An error occurred during assessment of the individual.

Encounter, episode and assessment codes

Record Encounter returns an encounter’s outcome in claimDetails.encounters[].information.code and each episode’s outcome in claimDetails.encounters[].episodes[].information.code. Update Encounter and Immunisation History Details return episode codes in the same information object.

Code	Meaning
`AIR-I-1000`	Encounter was recorded.
`AIR-W-1001`	Encounter was not recorded. Correct the details, or confirm and accept the episode status.
`AIR-E-0102`	Duplicate vaccination services are already on AIR.
`AIR-I-1002`	Vaccine was valid.
`AIR-I-1003`	Dose was adjusted. The episode’s `vaccineDose` holds the dose AIR recorded.

AIR also checks each episode against the individual’s existing history. When the check finds an issue, the episode’s information.code carries one of these assessment reason codes:

Code	Meaning
`AIR-W-0077`	Antenatal value may not be valid: the individual is not female, or is outside ages 10 to 65.
`AIR-W-0100`, `AIR-W-0115`	Antigen given under the minimum age.
`AIR-W-0101`, `AIR-W-0104`	Minimum interval between doses of the same antigen not met.
`AIR-W-0102`, `AIR-W-0103`	Duplicate antigen dose.
`AIR-W-0105`, `AIR-W-0112`	Dose is greater than the maximum allowed.
`AIR-W-0106`	A higher dose was already given by the same provider.
`AIR-W-0107`	Dose given later than the recommended schedule age.
`AIR-W-0108`	Dose given earlier than the recommended schedule age.
`AIR-W-0109`	A higher dose was already given by a different provider.
`AIR-W-0110`, `AIR-W-0111`	Less than 6 months between doses of the same antigen.
`AIR-W-0113`, `AIR-W-0114`	Dose given before the schedule age of 42 months.
`AIR-W-0116`	DTP dose 4 was already given before 42 months.
`AIR-W-0300`	Duplicate: the same provider already reported this service.
`AIR-W-0301`	Duplicate: another provider already reported this service.
`AIR-W-0303`	Duplicate history form episode.
`AIR-W-0305`	More than 5 episodes on the same date of service.
`AIR-W-0334`	Hepatitis B dose 3 given before 15 weeks of age.
`AIR-W-0400`	Accept and submit to AIR.

Reference data

The Reference Data endpoints return the vaccines, antigens and codes the other AIR endpoints accept. Take vaccine and antigen codes, and their descriptions, from these endpoints rather than hard-coding them. AIR caches each response for one hour, so a change takes up to an hour to appear. Store the reference data in your software, refresh it daily or weekly, and keep a way to force a refresh.

Display requirements

Services Australia sets what software using AIR shows its users. Full vaccine and disease names come from the Reference Data endpoints.

Endpoint	What your software shows
Authorisation	Only the services the response allows, under the labels on the Authorisation page.
Identify Individual	Each indicator that is `true`, as an alert or icon labelled: `catchupDate` “Planned Catch Up”, `medContraindicationIndicator` “Medical Contraindication”, `naturalImmunityIndicator` “Natural Immunity”, `vaccineTrialIndicator` “Vaccine Trial”, `actionRequiredIndicator` “Action Required”, `additionalVaccineIndicator` “Special Risk Group”.
Immunisation History Details	Each vaccine due, with the disease’s full name, the dose and the due date, earliest due date first or filterable. Each encounter, with the date of service, the vaccine’s full name, the dose, the status, the reason code and message text where present, the vaccine type and route as descriptions, and the antenatal indicator, most recent first or filterable. With nothing due, “There are no vaccinations due for this individual”. With no history, “No immunisation history is recorded for this individual”.
Immunisation History Statement	The PDF, which the user can download, view and print. The PDF is shown unaltered.
Medical Contraindication History	Each active contraindication with the vaccine’s full name, earliest start date first or filterable. With none, “No active medical contraindication is recorded for this individual”.
Natural Immunity History	Each active immunity with the disease’s full name, earliest notification date first or filterable. With none, “No active natural immunity is recorded for this individual”.
Vaccine Trial History	Each active trial with the disease’s full name, earliest start date first or filterable. With none, “No active vaccine trial is recorded for this individual”.
Add and Remove Additional Vaccine Indicator	The acknowledgement text before the user sets or clears the indicator. After an add, the Additional Vaccines Required alert. After a removal, the alert is cleared.
Indigenous Status Update	The current Indigenous status after a successful update from `false` to `true`.
Planned Catch-up Date	The acknowledgement text before the user submits, and the returned `catchupDate` on success.
Record Encounter	The valid vaccines as a pick list, and options to record past vaccinations and vaccinations given overseas.
Update Encounter	Only encounters the provider may edit, the valid vaccines as a pick list, and the updated encounter from Immunisation History Details after a successful update.
Record Medical Contraindication	Pick lists of the valid vaccines, the types (permanent or temporary) and the valid reasons for each type.
Record Natural Immunity	A pick list of the valid diseases.
Reference Data	A way for users to see the reference data your software uses.