NAV undefined
undefined
bash

Integration guide

Welcome! This page will help you to get started integrating Iluma's data products into your business flows. We will lay out some steps below to make the process of testing and development of your application as painless as possible.

1. Getting set up

Iluma data products use a RESTful API design to make them cleaner and easier to understand. All the API requests should be made over HTTPS instead of HTTP (all calls made over plain HTTP will fail). All our API responses will return JSON objects which can be consumed by your application. Responses will typically be delivered via callback, though some products also offer GET endpoints which you can poll to retrieve the status of a request.

This section will guide you through three steps

Getting sample code

To make it easier to get familiar with making API requests to our endpoints, we've published a Postman collection so that you can see examples of the latest version of Iluma APIs in one place. Instructions for getting started with this are here

Example code snippet to copy

curl https://api.iluma.ai/health

If you prefer to use terminal or some other tool to make requests, code samples are generally available in the right hand panel of this and other pages. You can copy these and drop them into your application of choice to make the relevant request.

We currently don't offer SDKs or libraries but if you are interested in us developing this please let us know what language and we will take the request to our development team.

Authenticating your requests

Example: Using the development API Key in this API documentation

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw

Option 1: Use the functionality built into your request library

Construct the API request with the API key as the username and no password

curl https://api.iluma.ai/v1/callback/authentication_tokens \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw:

Option 2: Manually construct the Authorization header for basic auth

First, add a colon at the end of the API key

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw:

Next, Base64 encode the colon appended key to get

aWx1bWFfZGV2ZWxvcG1lbnRfRlg0ZjBNNXN4RGdrNXFGeVpuazYwWmVuZ0FmQTlvMzF4M2VjZDI5dmloamM0Vmh5SjhGY2xaaEhqanc6

Then construct your API requests with the Authorization header

curl https://api.iluma.ai/v1/callback/authentication_tokens \
    -H 'Authorization: Basic aWx1bWFfZGV2ZWxvcG1lbnRfRlg0ZjBNNXN4RGdrNXFGeVpuazYwWmVuZ0FmQTlvMzF4M2VjZDI5dmloamM0Vmh5SjhGY2xaaEhqanc6'

For quick exploration of our services, you are welcome to use the development API key in this API documentation and the postman collection, but note that this is publicly available so we cannot guarantee isolation of your actions from others using the same keys. To develop for your own application, you should obtain API keys for the development and live environment. These can be obtained by contacting our sales team.

When you have an API key to use, there are two options for authenticating your request:

  1. Manually constructing an Authorization header OR
  2. Using the auth feature built into the request library you are using

Setting callbacks

As responses are delivered by callback you should set up a callback server. For the non-technical there are a range of SaaS sites you can use for quick testing purposes with dummy data (e.g., Webhook site, RequestBin), but we encourage you to set up a local server for testing and then expose it with something like ngrok to ensure that you maintain security of your end-user's data.

Once you have a local or SaaS callback server set up, use the instructions here to set up callback URLs for each of the endpoints. This involves:

  1. (Optional) Retrieving your callback authentication token
  2. Making a POST request to set callback URL for each of the services you want to test
  3. Your server returning a 2xx response to the test payload we send
  4. You receiving a success response to the POST request you made in step #2

2. Making your first request

Once you

You are now set up to make requests to the Iluma data product APIs. The latest list of endpoints is available here, with instructions on specific request and response formats. Generalised error formats apply across all endpoints and are available here.

We do this to make sure that we are protecting against the unintended exposure of personal data, while giving you the ability to safely hit the APIs during development of your application. This also means:

Given that it may be helpful to simulate test cases when developing your application we have configured our services to accept "Magic Reply" headers.

3. Simulating responses

When we receive a request with a "Magic Reply" header, we will return a response of a specific format, allowing you to simulate the major response payloads that you would receive when querying a resource with that state. If the response state would normally trigger a callback, this will also be sent to the server you specified during set up.

Note that:

Using "Magic Reply" headers.

To use the "Magic Reply" headers, you should supply an x-magic-reply header along with your normal request payload. The value supplied in this header will determine the response payload you are returned. In general, the simulate-able responses are typically:

More details.

bash