Patient Verification | RebateRight

Do the patient details I hold match Medicare’s record?

That is the question this endpoint answers, for one patient. Where the details differ, it returns the corrections Medicare shares.

This endpoint checks the patient details you hold against Medicare’s records: name, date of birth, sex, Medicare card number and Individual Reference Number (IRN). RebateRight checks the field formats first, then sends the details to Medicare’s Patient Verification Check service.

Reading the result

`Verified`	Result	Meaning
`true`	`patient verified`	Medicare has verified the patient’s details. Proceed.
`false`	`details don't match`	The details you hold do not match Medicare’s current record, or the patient’s card or Medicare cover is not current. `Reason` says which. Where details differ, correct the patient’s record before claiming.
`null`	`cannot determine`	The details could not be checked against Medicare’s record. `Reason` says what stopped the check.

patient verified does not confirm every field you sent. A different family name, sex or both still returns true when every other field matches. The corrections table below shows how Medicare treats each field.

cannot determine names its cause in Reason:

Cause	What to do
The request failed our format checks, so it never reached Medicare	Fix the field named in `Reason` and check again.
Medicare returned no assessment, such as for a reciprocal card or a deceased patient	Show `Reason`, which carries Medicare’s own sentence.
Medicare answered with a status RebateRight does not recognise	Show `Reason`, which carries what Medicare said.
The request to Medicare did not complete, because of an outage, a timeout or a connection problem on our side	`Reason` says what failed. Check again with the same request.

A Medicare error returns null, never false. Only false says the details do not match or the cover is not current. Eligibility Check uses cannot determine the same way, for an item that could not be checked, and lists its own causes.

Branch on Verified.

Corrections Medicare sends back

Where Medicare holds a different value and is willing to share it, that value arrives in the matching Correct… field. Every other Correct… field stays null.

What differs from Medicare’s records	`Verified`	Correction returned
Family name, sex or both, with every other field matching	`true`	None
Given name, first 5 characters still match	`true`	None
Given name, differs within the first 5 characters	`false`	`CorrectGivenName`
IRN	`false`	`CorrectMedicareReferenceNumber`
Date of birth	`false`	None
Medicare card number	`false`	None
The card has been reissued	`false`	`CorrectMedicareNumber`, `CorrectMedicareReferenceNumber`, `CorrectGivenName`

When 2 or more fields are wrong at once, Medicare returns no corrections. A wrong family name alongside a wrong given name also returns false with no corrections. Fix the fields you can and check again.

Patients with a single name

For single-name patients, submit the single name as PatientFamilyName and set PatientGivenName to the literal string ONLYNAME.

Using this check

Verify the details you already hold for a patient. Services Australia does not allow this check to be used to search for a patient whose Medicare details you do not know.

Services Australia also requires software that offers this check to:

show the date of the last verification against the patient’s record
offer to update the patient’s record with the details Medicare returns, where they differ

Display Reason exactly as supplied. Services Australia requires its messages to be shown to the end user exactly as supplied in the response, without truncating, transforming or changing them in any way. The wording can change at any time, so never parse Reason for logic.

Authentication

x-api-keystring

API Key authentication via header

x-minor-idstring

Your Minor ID is 3 uppercase letters followed by 5 digits, such as MDE00000. Send the Minor ID exactly as issued. A malformed value returns 400 with the text The Minor ID is not valid. on every endpoint.

Request

This endpoint expects an object.

PatientDateOfBirthdateRequired

Patient date of birth (YYYY-MM-DD). It cannot be a future date or more than 130 years in the past.

PatientFamilyNamestringRequired

Patient family name as it appears on the Medicare card. For single-name patients, put the single name here.

PatientGivenNamestringRequired

Patient first given name as it appears on the Medicare card. Medicare matches on the first 5 characters, so ELIZA is accepted against a record of ELIZABETH. For single-name patients, set this to the literal string ONLYNAME.

PatientSexenumRequired

Patient sex (Services Australia coding). A mismatch on sex alone still returns Verified: true, and Medicare returns no correction for this field.

Code	Meaning
`1`	Male
`2`	Female
`3`	Other
`9`	Not stated / inadequately described

Allowed values:

PatientMedicareNumberstringRequired

Patient’s 10-digit Medicare card number. It must pass the Medicare card check-digit routine, which RebateRight checks before sending the request to Medicare.

PatientMedicareRefNumberstringRequired

Individual Reference Number (IRN) from the patient’s Medicare card, a single digit identifying the family member.

DateOfServicedateOptional

Optional. The date to verify the patient against (YYYY-MM-DD). When omitted, Medicare verifies against today. It must not be in the future, must be less than 2 years before the request, and must not be before the patient’s date of birth. Send the date of service when you verify a patient for a service already given. A date that breaks these rules returns Verified: null, and Reason names the problem.

Response

Verifiedboolean or null

The outcome: true (patient verified), false (details don't match) or null (cannot determine). Reading the result above says what each value means and what to do.

Reasonstring

A plain-language explanation of the outcome, partly in Medicare’s own words. Display it exactly as returned.

ReasonCodestring

A machine-readable label for this outcome, always present.

Use it for analytics and grouping. Branch on Verified, which is stable. The codes are refined over time as RebateRight’s coverage grows, so treat them as an open set and expect values you have not seen before.

CorrectSexstring or nullOptional

Always null, because Medicare does not report corrections to sex.

CorrectGivenNamestring or nullOptional

Corrected given name when the given name is the only field wrong, or when a new Medicare card has been issued. null otherwise.

CorrectFamilyNamestring or nullOptional

Always null, because Medicare does not report corrections to family name.

CorrectDateOfBirthstring or nullOptional

Always null. Medicare names a date-of-birth mismatch in Reason and does not return the correct value.

CorrectMedicareNumberstring or nullOptional

Corrected 10-digit Medicare card number when Medicare has reissued the card. null otherwise.

CorrectMedicareReferenceNumberstring or nullOptional

Corrected IRN when the IRN was the only field wrong, or when a new Medicare card has been issued; null otherwise.