CLAIMING.COM.AU

Provider Onboarding and Security

Our Terminology

So that we’re all speaking the same language, here are the terms we use when referring to the entities involved with online claiming.

API

The API refers to the claiming.com.au API that you will be securely connecting to. There are currently 3 environments

  • http://api.claiming.com.au/demo (the public demo environment)
  • https://api.claiming.com.au/dev (the secure development environment)
  • https://api.claiming.com.au/v1 (the current stable production environment)

The demo environment is accessible here. It allows you to test real calls to the API from the walkthrough page. You can’t add other providers or create test groups in this environment.

Test data is available here. In the development environment there is a limited pool of valid providers and patients,

For development purposes, we will issue you with Vendor Dev keys which will allow you full access to the http://api.claiming.com.au/dev environment. Here you can run all calls available in the API including adding new sites (we call them Auth Groups), adding dummy providers, and making dummy claims.

When development is complete we will issue you with keys to the production environment https://api.claiming.com.au/v1 where your customers can verify patient details in realtime, submit live claims to Medicare & DVA and retrieve processing & payment reports.

Vendor

A vendor is any software vendor integrating with our API, that’s you!

Vendors are responsible for maintaining their own lists of authorised users. Before the API can process transactions for your authorised users (Providers), you’ll need to let us know some details about who they are and if any of them are connected in some way, for example in a group practice. We call these ‘Auth Groups’.

A Vendor will need to manage many Auth Groups, typically one for each customer site.

Auth Group

An Auth Group is a list of providers who submit claims and access reports together. In general it can be considered synonymous with a practice site.

If you have dealt with Medicare before, you may equate this with ‘LocationID’ or ‘MinorID’, all three are equivalent for our purposes. The MinorID looks like SAP12345 and is a unique identifier used in electronic claiming to show where the claim is coming from.

The actual MinorID value is a field of Auth Group, and needs to be registered with Medicare and linked to providers (details below).
*IMPORTANT - the Minor ID used in development will not be used in production, do not use the development Minor ID to register providers with Medicare!*

An Auth Group may be used for any of the following scenarios:

  • an individual practitioner using a single provider number
  • an individual practitioner using many provider numbers (e.g for work in different hospitals)
  • a group practice with a combination of the above.

Separate Auth Groups are required where a business operates a number of different offices or franchises that require separate banking arrangements.

Provider

In our terminology, a Provider is a medical or allied health professional with a unique Medicare provider number, providing a type of service in an Auth Group.

This is distinct from a Practitioner - we define a Practitioner as a person who may have several provider numbers when:

  • rendering services at different locations,

  • providing different types of service (a Dentist who is also a Surgeon, or a Physiotherapist who is also a Dietitian),

  • working for different businesses (and therefore in different Auth Groups).

The claiming.com.au API does not store any knowledge of Practitioners, only their name as set in the Provider table.

Each Provider is linked to one Auth Group and is identified by their provider number issued by Medicare.

Claim

Each provider can submit electronic claims using our API.

A claim is a submission to a Registered Health Fund, Medicare Australia or the Department Of Veterans Affairs for services provided to a patient, which may result in the provider, the patient or a third party receiving a payment.

In the API each claim:

  • can only be for one servicing provider

  • can only be for one patient

  • can only be for services at one location

  • can only have one referrer (if one is required)

  • generally can have any number of service items, which can be on different dates of service (some restrictions apply in special cases)

API Authorisation

All requests to the claiming.com.au API use oAuth.

The API uses two types of authentication.

  • Vendor authentication grants API access to submit and retrieve data for all Auth Groups which belong to the Vendor, and to create new Auth Groups. Solutions that only make calls to the API from a server will need only this.

  • For installed software, vendors must use Auth Group authentication, to limit API access to claims for providers in that Auth Group. Adding and updating Auth Group details and provider details requires Vendor authentication.

For a Vendor to submit and retrieve Claims on behalf of one of their Auth Groups, an extra querystring parameter "?auth_group=?" must be set to identify which group they are working with. The remainder of the request will be sandboxed to objects belonging to the Auth Group.
NOTE: If you're authenticating with Auth Group-level credentials, the "?auth_group=?" querystring parameter does not need to be set.

Medicare Certificates

Providers DO NOT require their own Medicare certificates to use the API, which has its own secure connection to Medicare.

Providers may want to have a Medicare Location Certificate for other purposes such as accessing the Health Providers Online Services portal (HPOS). This is fine and won't interfere with their access to eclaiming using our API. We don't provide support for these other uses.

API Calls

Let’s examine the API calls which deal with these entities. The examples below are all in the Dev environment so will require Vendor Dev keys.

HTTPS GET calls are made with a simple URL.

HTTPS POST calls require the appropriate, well-formed JSON to be included in the body of the POST.

Some calls require an additional query string in the URL to indicate the Auth Group.

/oauth/token

To use your client ID and secret to generate an oAuth token, please use the /oauth/token command.

POST https://api.claiming.com.au/dev/oauth/token

With the following payload, replacing the client_id and client_secret with the ones we provided:

{
  "client_id": "XXXXXXXXXXXXXXXXXXXX",
  "client_secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "grant_type": "client_credentials"
}

The response object has the token you'll use in the rest of your calls to authenticate, as well as when that token expires.

{
  "access_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "expiry": "2018-08-10T11:13:16-04:00"
}

The token should then be provided in the Authorization header like so:

curl -H 'Content-Type: application/json' -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' https://api.claiming.com.au/dev/whoami

/whoami

To confirm the Vendor and Auth Group details, we use the whoami command.

GET https://api.claiming.com.au/dev/whoami

The response object has the Vendor Name and ID, and a list of linked Auth Groups for that Vendor

{
  "authGroup": {
    "Id": 2,
    "Label": "Dev Auth Group"
  },
  "vendor": {
    "Id": 2,
    "Name": "Dev Vendor"
  }
}

Then there are 3 Auth Group API calls

  • /auth_group/list - retrieves a list of Auth Groups which are registered to the Vendor
  • /auth_group/add - adds a new Auth Group
  • /auth_group/update - updates Auth Group details (which includes an ‘active’ flag for ‘deleting’)

Auth Group calls

/auth_group/list

The command

GET https://api.claiming.com.au/dev/auth_group/list

returns a response object in this case showing there are 2 Auth Groups for this Vendor, one with a MinorID of SAP00001 and 2 providers; and the second with a MinorID of SAP00015 and 1 provider. The second site is flagged as inactive, and therefore API calls for that Auth Group will be rejected.

{
    "status":"OK",
    "items":[
        {
            "id":1,
            "minorID":"SAP00001",
            "name":"Dev Auth Group",
            "providers":[
                {
                    "providerNumber":"2418291F",
                    "name":"Augustus Eason",
                    "active":true,
                    "address1":"12 Smith St",
                    "address2":null,
                    "suburb":"Richmond",
                    "postcode":"3121",
                    "state":"VIC"
                },
                {
                    "providerNumber":"2418301X",
                    "name":"Gaye Jackson",
                    "active":true,
                    "address1":"10 High St",
                    "address2":null,
                    "suburb":"Epping",
                    "postcode":"3111",
                    "state":"VIC"
                }
            ],
            "active":true
        },
        {
            "id":15,
            "minorID":"SAP00015",
            "name":"Test Site",
            "providers":[
                {
                    "providerNumber":"2418291F",
                    "name":"Justine Example",
                    "active":true,
                    "address1":null,
                    "address2":null,
                    "suburb":null,
                    "postcode":null,
                    "state":null
                }
            ],
            "active":false
        }
    ],
    "total":2,
    "offset":0
}

/auth_group/add

With a Vendor Certificate, you can add an Auth Group for each of your sites by passing in JSON in the body of a POST. You can also add providers at the same time to the newly created Auth Group.

POST https://api.claiming.com.au/dev/auth_group/add
{
    "name": "Jane's Practice",
    "providers": [
        {
            "name": "Jane Smith",
            "providerNumber": "2418291F",
            "address1":"12 Smith St",
            "address2":null,
            "suburb":"Richmond",
            "postcode":"3121",
            "state":"VIC"
        },
        {
            "name": "Bob Jones",
            "providerNumber": "2418301X"
        }
    ]
}

The response object will contain an “id” for the newly created Auth Group.

{
    "id":17,
    "minorID":"SAP00017",
    "name":"Jane's Practice",
    "providers":[
        {
            "providerNumber":"2418291F",
            "name":"Jane Smith",
            "active":true,
            "address1":"12 Smith St",
            "address2":null,
            "suburb":"Richmond",
            "postcode":"3121",
            "state":"VIC"
        },
        {
            "providerNumber":"2418301X",
            "name":"Bob Jones",
            "active":true,
            "address1":null,
            "address2":null,
            "suburb":null,
            "postcode":null,
            "state":null
        }
    ],
    "active":true
}

If you repeat the auth_group/list call at this time you will see the added Auth Group.

/auth_group/update

Vendors can update Auth group details with:

POST https://api.claiming.com.au/auth_group/update
{
    "id": 17,
    "name": "Dr Jane's practice",
    "active": true
}

The response confirms the updated detail. The associated providers weren’t updated, so no details are returned.

{
    "id":17,
    "minorID":SAP00017,
    "name":"Dr Jane's practice",
    "providers":null,
    "active":true
}

/auth_group/id/oauth

Vendors can create OAuth credentials specific to the auth group with:

POST https://api.claiming.com.au/auth_group/17/oauth

The response includes the client ID and secret for the new credentials.

{
    "ClientId": "XXXXXXXXXXXXXXXXXXXX",
    "ClientSecret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Note: Subsequent calls to /auth_group/id/oauth will delete the old credentials and create new ones.

Provider calls

The methods for adding and updating Providers are similar.

  • /provider/list - Lists the providers in the Auth Group
  • /provider/add - Adds a provider to the Auth Group
  • /provider/update - Updates a provider’s details, including the ‘active’ flag, which can be set to false for deleting
  • /provider/{provider number} - Removes a provider from an auth group (REST verb: DELETE)

These requests require an auth_group flag to be set in the query string on the URL

/provider/list

The command

GET https://api.claiming.com.au/dev/provider/list?auth_group=17

will return a response object listing the providers in the specified Auth Group, which must be one of the groups linked to the Vendor. Attempts to request information for an Auth Group which is not associated with the Vendor will return the error

{
    "message":"Auth Group not valid for the provided certificate",
    "status":"FORBIDDEN"
}

/provider/add

To add a provider to an Auth Group use the syntax

POST https://api.claiming.com.au/dev/provider/add?auth_group=1
{
    "name": "Jane Smith",
    "providerNumber": "2418291F",
    "address1":"12 Smith St",
    "address2":null,
    "suburb":"Richmond",
    "postcode":"3121",
    "state":"VIC"
}

/provider/update

To update details of an existing provider use the syntax (where providerNumber is the unique ID)

POST https://api.claiming.com.au/dev/provider/update?auth_group=1
{
    "providerNumber": "2418291F",
    "active": false
}

Note:
This is NOT a RESTfull URL, the ID is taken from the submitted object, not the URL.

/provider/{provider number} (DELETE)

To remove an existing provider, use the syntax (where providerNumber is the unique ID)

DELETE https://api.claiming.com.au/dev/provider/2418291F?auth_group=1

Note:
If a provider is associated with one or more claims, you will not be able to delete the provider.

Putting it all into practice

Here's a step by step guide to on-boarding sites and providers. The steps vary slightly depending on the design of your software.

Server-based PMS software

If your PMS runs from a central server, with all API calls originating from that server (e.g a SaaS product) then you will only need Vendor authentication to secure all communications between your server and ours. We expect that you will manage the secure connection between your server and your clients, for example with HTTPS.

  1. You will need to obtain Vendor oAuth credentials (client_id and secret) from us.

  2. Authenticate to the API via the POST /oauth/token endpoint to get your API token.

  3. Using your Vendor authentication, create an Auth Group for each site that will submit claims with /auth_group/add. You will need to store the Auth Group ID and Minor ID for each group created. Sites will need to know their Minor ID when completing paperwork for Medicare.

  4. Using your Vendor authentication, add providers to each Auth Group (NOTE you can combine steps 2 & 3 with the extended syntax of /auth_group/add, or you can add providers to an existing Auth Group with /provider/add)

  5. Ensure each provider has completed the required paperwork for Medicare (see below).

  6. Once that's all done, you can transmit verification requests and claims for your sites, using their Auth Group ID to identify the site.

Installed PMS software

If your PMS is installed at each site, and API calls will be between those sites and our server, then in addition to your Vendor authentication you will also need to generate Auth Group credentials for each site using your Vendor oAuth credentials.

  1. Using your Vendor oAuth credentials, create an Auth Group for each site that will submit claims with /auth_group/add. The site will need to know their Minor ID when completing paperwork for Medicare.

  2. Add providers to each Auth Group (NOTE you can combine steps 2 & 3 with the extended syntax of /auth_group/add, or you can add providers to an existing Auth Group with /provider/add)

  3. Issue each site with an Auth Group credentials so they can make API calls.

  4. Ensure each provider has completed the required paperwork for Medicare (see below).

  5. Once that’s all done, each site can transmit verification requests and claims. Note that API calls with Auth Group authentication type don’t need to specify the Auth Group ID, this is linked to the credentials.

Special note for Vendors currently transmitting claims under another Medicare Notice of Integration (NOI)

If you're migrating providers who are currently submitting electronic claims with another product then check with us about the requirements to make the transition smoothly. A provider number can only be linked to one Minor ID, and claims with the old software must be completely processed before submitting new paperwork to Medicare.

Medicare Paperwork

Before providers can submit electronic claims, each will need to complete some paperwork and forward it to Medicare Australia. We recommend that you assist them with this process by providing the following information.

Online Banking Details Form

In order to successfully lodge claims with Medicare, all providers within an Auth Group will need to fill out this form, with the Minor ID allocated to their Auth Group.

The purpose is to link Provider Numbers with a bank account and a Minor ID. One or more provider numbers for one or more practitioners can be entered on this form if they are all linked to the same bank account and Auth Group. Conversely, any provider number can only be linked to one bank account and Minor ID (Auth Group), so the details on the form will replace any older details held by Medicare for that provider number. If a Practitioner requires funds for different services to be paid into different bank accounts they will need to apply to Medicare for additional provider numbers.

Claims cannot be sent until the Online Banking Details form with the correct Minor ID has been received and processed by Medicare.

Online Claiming Provider Agreement

If a provider has never registered for online claiming they will also need to fill out this form with the Minor ID allocated to their Auth Group. The purpose of this is to confirm they wish to conduct business electronically with the Department of Human Services, and accept the relevant terms and conditions.

All that is needed is their name, signature and one provider number, everything to do with certificates can be ignored, as we manage that for you and the providers.

Medicare Location Certificates

We have gone to a lot of trouble to make the on-boarding process as simple as possible. As mentioned above, there is no need for your practices to apply for Medicare Certificates to use the API. If anyone has been otherwise advised, please let us know so we can streamline the process for them.