Technical Guide

This section of the documentation is intended for technical parties e.g. web or application developers.

API Keys & Access Tokens

When you become a registered integrator with VaultRE you will be provided with an API Key. This API Key is unique to you and identifies you to VaultRE when you use the API. You must keep the API Key secret and not divulge it to other parties.

The Access Token provided to you by the client is what grants you access to their VaultRE account via the API. You may have many Access Tokens, one (or more) per customer.

Note that each Access Token has a set of scopes applied, as chosen by the customer. To view the scopes assigned to a token, you can call GET /scopes on the API.

Instead of having your clients manually generate Access Tokens, you can use oAuth to have them generate tokens easily from within your system. See the oAuth Guide for more information.

Note that each Access Token has a set of scopes applied, as chosen by the VaultRE client. To view the scopes assigned to a token, you can call GET /scopes on the API.

Swagger Documentation

The documentation for the API is available at the below link:

https://docs.api.vaultre.com.au/swagger/index.html

The documentation is a Swagger API website which allows you to interact with the API directly from the website for testing purposes.

Consult the documentation for the latest information on the API.

Endpoint

Currently, the base API endpoint is:

https://ap-southeast-2.api.vaultre.com.au/api/v1.3/

Please note that all requests must be over HTTPS.

Data Format

The API transfers data in the JSON format.

Date/Time Format

Generally, the API returns the following format for Date objects:

YYYY-MM-DD

e.g. 2016-04-28

and the following format for DateTime objects:

YYYY-MM-DDThh:mm:ss+z

e.g. 2018-05-22T01:12:59+00:00

Please note that all times are 24-hour and usually in the UTC timezone. You can submit DateTime objects in whatever timezone you prefer.

Photo Hotlinking

We require third-party integrators (anyone using our API, Webhook or XML Feeds) to download the image files and host them locally. This benefits both parties as you will have no reliance on our servers being up for the website to stay functional, and we will not receive any increased load or bandwidth. Using the modtime you can tell if the image needs to be re-downloaded if updated. Hotlinking to images is discouraged and will result in the feed being disabled until resolved. Please note that access to images may be removed at any time if hotlinking is detected.

Authorisation & Authentication

All requests must include a header X-Api-Key: {your API key here} or a 403 Forbidden error will be returned.

All requests must also include a header Authorization: Bearer {client’s access token here}.

Rate Limiting

All API Keys are rate limited to 10 requests per second and 10,000 requests per day (with a quota reset time of 00:00 UTC). Therefore, you should cache data appropriately to avoid using up your allocated quota.

If you are retrieving property listings from the API to power a website, our recommendation is that you do not call the API "live" on each page load as this introduces the API as a direct dependency on your website performance and puts you at risk of exhausting your allocated quota. Rather, you should synchronise data periodically and cache it locally.

When you are being rate limited, the API will return a HTTP 429 response.

Webhooks

VaultRE is able to send webhook events to your nominated endpoint, advising you in real time of updates to data in VaultRE. For more information, view the webhooks guide

Versioning

The JSON payload from various endpoints is subject to change at any time. Within a minor version (e.g. 1.0, 1.1, 1.2, 1.3) fields can be added to a JSON payload but we will endeavour to never make breaking changes (e.g. removing a field or changing a field's data type). Between versions, breaking changes may be made. Your application should be able to handle new fields being added to the JSON payload arbitrarily.

Assistance

If you need assistance integrating your application/website with VaultRE, please email api@vaultre.com.au. We can't build your integration for you but we're happy to assist you wherever possible.