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 with no Medicare card number, such as newborns, newly arrived immigrants and student visa holders.

RebateRight and AIR

RebateRight is certified by Services Australia and sends your AIR requests for you.

Before your first AIR request

Setting up for the AIR sets out what each vaccination location needs before its first AIR request.

AIR checks the Minor ID in x-minor-id against the information provider number on every request.

Code	When AIR returns it
`AIR-E-1039`	The provider number is not linked to that Minor ID
`AIR-E-1063`	AIR 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. 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:

Status	Cause
`400`	A missing body or Minor ID
`401`	A missing or invalid API Key
`503`	RebateRight cannot complete the request

Errors and retries 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.

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`	An unexpected error at the AIR. Send the request again shortly. If the error continues, contact the AIR Internet Helpdesk, as Services Australia’s message advises, or send us the `correlationId` and we will trace the request.
`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.

Codes. Take vaccine and antigen codes, and their descriptions, from these endpoints rather than hard-coding them.
Caching. AIR caches each response for one hour, so a change takes up to an hour to appear.
Storage. 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, including each AIR message exactly as AIR returns it (Messages). AIR display requirements gives the rules for each endpoint.