whoami - Confirming your connection to the API

Let's start with a simple 'whoami' check to make sure everything is working.

The response will show you the name and other information about the authorised user, and the range of claim types available to that user, eg Medicare, DVA etc.

Who Am I?

verify - Checking a patient's details

I'd like to introduce you to Bernhardt. Bernhardt is a mythical person, who was born in 1974 and lives in Carlingford.

Let's check Bernhardt's Medicare card number.

Our demo API checks against a mock set of Medicare cards, you won't be able to check actual Medicare card data in the demo.

The status section gives you information on the result of the verification. In this case, it's a '0', which means no details need correcting.

There are four types of patient information which can be verified, you'll notice the extra elements "dva" and "fund" in the response.

  • Medicare Verify:Medicare - the most common of verification types, most Australians have a Medicare card which entitles them to various rebates for medical activities.

  • Concession Verify:Concession - cards are granted to some Australians to provide a discount for health services - Other than the concession card details, concession claims are identical to Medicare claims. No concession card information can be returned by the adapter, only a status.

  • DVA Verify:DVA - is for checking Veterans' card details with the Department of Veterans Affairs. Claims for veterans with this card are handled by Medicare on behalf of DVA, sometimes using different item numbers and claim rules.

Who Is Bernhardt?

{ "type": "Verify:Medicare", "patient": { "dateOfBirth": "1974-02-28", "medicare": { "number": "2952631861", "ref": 1 }, "gender": "M", "name": {"first": "Bernhardt", "family": "Griffith"} } }

Verification can correct the patient's first name

Let's see what happens if we change Bernhardt to Bernie.

Bernhardt's first name has been corrected. The Medicare database is not case sensitive, hence the capitals.

The codes (0 and 8005 so far) are called 'Medicare Error Codes', you can access our list of these codes and their meanings here

You can also replace the 'type' field with the codes from above to perform other types of verifications.

Bernhardt isn't Bernie

{ "type": "Verify:Medicare", "patient": { "dateOfBirth": "1974-02-28", "medicare": { "number": "2952631861", "ref": 1 }, "gender": "M", "name": {"first": "Bernie", "family": "Griffith"} } }

Verification can update Medicare Card details

We can also update card information, for example if a new medicare card has been issued.

The returned code 8005 or 9633 indicates details have been updated.

That's it for "Verify:Medicare" type verifications, play around with the elements to see how it reacts. You'll notice that Medicare doesn't check ALL fields, and sometimes isn't able to match the patient at all.

Gregory Watts' Medicare Card

{ "type": "Verify:Medicare", "patient": { "dateOfBirth": "1970-05-12", "medicare": { "number": "2298264833", "ref": 1 }, "gender": "M", "name": { "family": "WATTS", "first": "Gregory" } } }


Claims are a little more complex, the request object consists of:

  • Patient Details
  • Name
  • Date Of Birth
  • Fund Membership (e.g. Medicare or DVA card details)
  • Practitioner / Medical Professional Details
  • Uniquely identifying 'Provider Number'
  • Referral / Request details (where required)
    • Referring / Requesting Practitioner's Provider Number
    • Referral Date and period
  • General Details
    • The Type of claim being submitted (DVA, Medicare, Bulk Bill, In Patient Medical)
    • Location of service (In Hospital, Consulting Rooms, At Home etc)
    • Date of service
    • Various other details required for specific claim types
  • List of Items
    • Item Number - Unique identity of an item, there are a few sets of identifiers, like 'MBS' or 'DVA'
    • The dollar and cents amount the practitioner charged for the item
    • Any extra details on the items depending on the claim type

My First Claim

{ "type": "BulkBill", "flags": { "serviceType": "O" }, "patient": { "dateOfBirth": "1974-02-28", "medicare": { "number": "2952631861", "ref": 1 }, "gender": "M", "name": {"first": "Bernhardt", "family": "Griffith"} }, "provider": { "servicing": "2433411Y" }, "items": [ { "chargeAmount": "50.50", "date": "TODAY", "itemNumber": "00104" }] }

Claims can have more than one item

Place as many different items and dates of service as required for the claim into the items array.

Note that each claim can only be for one servicing provider and one patient

{ "type": "BulkBill", "flags": { "serviceType": "O" }, "patient": { "dateOfBirth": "1974-02-28", "medicare": { "number": "2952631861", "ref": 1 }, "gender": "M", "name": {"first": "Bernhardt", "family": "Griffith"} }, "provider": { "servicing": "2433411Y" }, "items": [ { "chargeAmount": "50.50", "date": "TODAY", "itemNumber": "00104" }, { "chargeAmount": "50.50", "date": "TODAY", "itemNumber": "00105" }, { "chargeAmount": "50.50", "date": "TODAY", "itemNumber": "00106" }, { "chargeAmount": "50.50", "date": "TODAY", "itemNumber": "00107" }] }

DVA claims have a similar structure

Our API is designed so that each claim type has a similar structure.

The main difference with a DVA claim is that is has a DVA node for the Veteran's details.

Medicare details are not required for DVA claims, however, including them isn't an error.

The API is intended to allow you to write one function which prepares the entire 'patient' node, and use it for all types of claim and verification

Note that if the patient is a White Card holder then claims are only allowed for the condition specified on the White Card. The underlying condition needs to be included in the DVA node.

{ "type": "DVA", "flags": { "serviceType": "O" }, "patient": { "dateOfBirth": "1950-05-07", "gender": "M", "name": { "family": "GAYLE", "first": "Angiolina" }, "dva": { "number": "VX900687", "disability": "PTSD" }, "address": { "locality": "HAMILTON", "postcode": "3300" } }, "location": { "provider": "9988770W", "type": "R" }, "provider": { "payee": "2418291F", "servicing": "2433411Y" }, "items": [ { "chargeAmount": "84.70", "date": "TODAY", "itemNumber": "30195" } ]}


The server runs the claim through a number of stages. If any of them fail, an error is returned, and that's the end of the processing.

The server will always return as many error messages as it can, for example, if there are two elements, a number and a date, which are set to an invalid format, both fields will be returned in the error message, with their own descriptions.

Check One: JSON Format

Is the request a valid JSON object. The rejection returned might not give you enough detail to find the fault, use 'python -m json.tool' or to get a better error.


{ "busted""json""object }

Check two: Data Format

Are all elements in their correct data format?

  • Dates are given as "YYYY-MM-DD", Times "HH:MM", DateTime "YYYY-MM-DD HH:MM"
  • Numbers are either numbers, or strings containing numbers
  • Booleans are either booleans, 1 or 0, "Y"/"N", "y","n" etc. (Use actual true/false where possible, it's just cleaner that way.)
  • Enum fields contain a string for one of the enum options.

The 12th of never

{ "type": "Verify:Medicare", "patient": { "dateOfBirth": "1963-Never-12" } }

Check three: Logic

There are many logic rules to check against. If the claim doesn't meet one, the server will attempt to continue validating as far as it can, and return all logic validation errors in one go. (e.g. Medicare requires that Allied Health Claims come with a referral, or a referral override code).

I wasn't born yesterday!

{ "type": "BulkBill", "flags": { "serviceType": "O" }, "patient": { "dateOfBirth": "TODAY", "medicare": { "number": "2950552261", "ref": "1" }, "name": { "family": "GAYLE", "first": "Angiolina" } }, "provider": { "servicing": "2433411Y" }, "items": [ { "chargeAmount": "50", "date": "YESTERDAY", "itemNumber": "00104" }] }

If everything checks out, and the claim looks valid, the claim is given a UID and stored.

And just in case Prince does need to put through a claim, Medicare accepts a surname of "ONLYNAME"

The artist formerly known as...

{ "type": "BulkBill", "flags": { "serviceType": "O" }, "patient": { "dateOfBirth": "1980-01-01", "medicare": { "number": "2297460335", "ref": "1" }, "name": { "first": "Devo", "family": "ONLYNAME" } }, "provider": { "servicing": "2433411Y" }, "items": [ { "chargeAmount": "50", "date": "TODAY", "itemNumber": "00104" }] }


After a claim is submitted, it progresses through a number of queues in the server and with medicare. Some claims will be assessed by a human, and can take more than a week to process.

There are two ways to get the status of a claim.

Checking the status of a single claim by Unique ID

The simplest way to check a claims status is a direct request by its Unique ID

The response given is the same object which was submitted initially - with a few changes.

The claimId has been added - that's not so useful in this request, but makes more sense in a list request.

A 'status' field has been added. The information available here varies between claim types. For medicare type claims, the status is only 'NEW', 'INVALID' and 'COMPLETE' - there is no feedback from Medicare on those reports

Claim objects containing fields which don't exist cause the claim to be rejected, unless they are prefixed with an underscore. This feature allows you to add any custom IDs and flags you may require. The underscore fields will always be returned verbatim with any responses.

You may also notice datatype fixes on some fields. ("1234" becomes 1234, "Y" becomes true etc)

Simulating Processing of Claims

A claim begins its digital journey in a waiting room with a status of [NEW].

The API queues claims and sends then to Medicare Online Services one by one at a throttled pace.

For some claims, that is the end of the journey - There is currently no way to track the progress of a 'Store And Forward' claim, which is the type we use for Medicare submissions. Those claims will get a status of [COMPLETE]

IMC Claims have a detailed status structure as they progress through Medicare to the Health Fund and back.

For the other types (currently DVA, Bulk Bill), the journey has just begun. Once submitted, they have a status of [WITH MEDICARE].

To progress the claim in development, you can simulate a 'Processing Report'

Make the call to the right, then check the status again (above) to see the change.

The default call sets the claim to be fully successful. To simulate more complex results, you can set querystring parameters.

The processing report outlines the benefit various organisations will pay for the claim. If all of those are $0, the claim will be marked as [COMPLETE], and no more information is expected

If an organisation will be paying a benefit, the status will be [PROCESSED] until it has been paid, which will again have a status of [COMPLETE]


sets the benefit of the 1st item to be $15.50


sets the 'reason code' of the 3rd item to be 125

Easier than a phone call

Simulating Payment of Claims

Payments are recieved in 'Payment Runs', which can cover more than one claim.

To simulate a payment, you only need to specify the list of claims to include. (comma seperated)

Once you have simulated the payment, you will see a 'payment' item on the claim, which gives you the ID for a subsequent call

Checking the status of a range of claims

Another way to retrieve status of claims, and to retrieve payment reports, is to make a list query.

There are a few parameters you can use, and let us know if there is somthing else which you would find useful.

limit Sets the maximum number of claims to return in the response. (default = 10, maximum = 50)

offset Sets the offset from 0 for the first claim to return, not a 'page' (default = 0, no maximum)

since Probably the most useful - only returns claims which have changed since the timestamp given