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
- Authenticating your requests
- Setting callbacks
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
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
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
Authorizationheader for basic auth
First, add a colon at the end of the API key
Next, Base64 encode the colon appended key to get
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
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:
- Manually constructing an Authorization header OR
- Using the auth feature built into the request library you are using
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:
- (Optional) Retrieving your callback authentication token
- Making a POST request to set callback URL for each of the services you want to test
- Your server returning a 2xx response to the test payload we send
- You receiving a success response to the POST request you made in step #2
2. Making your first request
- Have an API key
- Have a callback server
- Have set up callbacks
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:
- There is no cost for making requests in development mode
- Changing your input payload may not achieve a different response payload
- You cannot rely on the verification results in this environment
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.
- Requests made to validation endpoints (e.g., ewallet name validation) will mirror your request payload
- Requests made to data extraction endpoints (e.g., ID card OCR) will return dummy data
- Format validation will be applied before assessing the magic reply header, so you will receive
API_VALIDATION_ERRORif you provide a request payload which doesn't comply to the API specification
- These headers are available in BOTH
- Requests made with these headers will NOT be charged in the
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:
- Pending: Your request has been submitted but the response has not yet been received from the data source. No callback will be sent for this state.
- Completed: Your request has completed processing
- Data found: Data has been found or extracted. A callback will be sent
- Data not found: Data has not been found or was unable to be extracted. A callback will be sent
- Failed: Your request encountered an error during processing