Getting Started
The Developer API is built using a standards based HTTPS API using JSON as the data-interchange format.
API URIs#
There are two URIs for each state that developers must be aware of, the staging URI and the live URI:
info
Each state uses different usernames and passwords
The "staging" sites are a separate copy of system and is to be used for development purposes. Developers should not be developing their applications using the live api.
SSL#
Due to the sensitive information being transferred between the client and the API, all requests are required to be sent over HTTPS. Any requests made to a non-secure URI will be redirected to equivalent HTTPS URI.
Key#
Before you can start making requests to the API, you will require an API key. This key is unique to your organization/product and must be kept private. Each key is tied to a specific authentication type outlined below and in combination with an end-user token will allow you to authenticate against the API and perform requests on behalf of an end-user.
Register here to request an API Key.
JSON#
Requests and responses from the Developer API use the JSON data-interchange format. This requires all requests to send a content type header of application/json. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.
HTTP Verbs#
All HTTP requests are made using one of four verbs (GET, PUT, POST, DELETE). Each verb has it's own meaning:
| Status Code | Description |
|---|---|
| GET | Retrieve the specified resource |
| PUT | Update the specified resource |
| POST | Create the specified resource |
| DELETE | Delete the specified resource |
All documented endpoints specify their required HTTP verb.
Responses#
When the API responds to a request, it will return a HTTP status code depending on whether the response was successful or a failure. Any of the following responses can be returned:
| Status Code | Description |
|---|---|
| 200 | The request was successful |
| 400 | Bad request, check your input parameters |
| 401 | Unauthorized, invalid or expired token |
| 403 | Forbidden, insufficient permissions |
| 404 | Not Found, the resource could not be found |
| 500 | Internal Server Error, something went wrong |
Deep Linking#
There may be cases where you want to redirect an end-user to the UI application to view or finish a form. For this purpose, you can create a user token and follow the below instructions to link into the application.
- Retrieve a user token using the Create User Session end point
- Use the table below to determine the base URI for the state you wish to deep link to:
- Using the following format BASE_URI/?token=TOKEN#PATH to generate your deep link, e.g:
- ✅ https://nsw.reiformslive.com.au/?token=XXX#news - deep link to the news page
- ✅ https://tas.reiformslive.com.au/?token=XXX#forms - deep link to the forms index
- ✅ https://app.realworks.com.au/?token=XXX#form/123/display - deep link to the form with the ID of 123