Quickstart

This guide will get you all set up and ready to use the Forms Live API. We will cover how to get started with authentication and how to make your first API request. We will also look at where to go next to find all the information you need to take full advantage of our powerful REST API.

Understanding the API structure

Forms Live API is a standards-based HTTPS API using JSON as the data-interchange format. The API is available for multiple Australian states, each with its own staging and production endpoints.

API Endpoints

Each Australian state and territory has dedicated staging (development) and production endpoints:

Setting up authentication

Forms Live API uses a third-party authentication method that requires a combination of your API key and an access token provided by the end-user. This method is secure and allows end-users to control which third parties can access their account.

Follow these steps to set up authentication:

1. Obtain your API key from the Forms Live developer portal
2. Get an access token from the end-user (generated via the Forms Live/Realworks user interface)
3. Create the Authorization header by combining and encoding the key and token

# Example key
a9d9b0a7-1365-4781-85b3-0fbb36ecd230

# Example token
258170b7-d02b-4f8b-aa41-2976f172fa21

# Combine with colon
a9d9b0a7-1365-4781-85b3-0fbb36ecd230:258170b7-d02b-4f8b-aa41-2976f172fa21

# Convert to base64
YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ==

# Authorization header
Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ==

Making your first API request

After setting up authentication, you are ready to make your first call to the Forms Live API. Below, you can see how to send a GET request to the Forms endpoint to get a list of all your forms.

curl https://nsw.api.reiformslive.com.au/forms/ \
  --request GET \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ=="

This will return a list of forms that the authenticated user has access to.

Understanding HTTP responses

When the API responds to a request, it will return an HTTP status code indicating whether the request was successful or not:

Deep linking to the Forms Live UI

For cases where you want to redirect an end-user to the Forms Live UI to view or finish a form, you can create a user token and construct a deep link:

1. Retrieve a user token using the Create User Session endpoint
2. Use the appropriate base URI for the state you wish to link to
3. Construct your deep link using the format: BASE_URI/?token=TOKEN#PATH

# Deep link to the news page
https://nsw.reiformslive.com.au/?token=XXX#news

# Deep link to the forms index
https://tas.reiformslive.com.au/?token=XXX#forms

# Deep link to a specific form
https://app.realworks.com.au/?token=XXX#form/123/display

What's next?

Great, you're now set up with authentication and have made your first request to the API. Here are a few links that might be handy as you venture further into the Forms Live API:

• Request your API key from the Forms Live developer portal
• Check out the Forms endpoints
• Learn about the Form Files API
• Explore Electronic Signing functionality
• View the session endpoint