Introduction

Welcome! Here at Iluma, our mission is to provide digital infrastructure that helps you succeed. We help with data products to support your Know-Your-Customer (KYC) processes, and reduce risk for both money in (accepting payments) and money out (disbursing payments). Use cases range from platform business to fintech lending and eCommerce, and everything else in between.

The Iluma API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors. These APIs are versioned by route and the latest version(s) will always be available here.

Learn our APIs with Postman

To make it easier to get familiar with our APIs, we've published a Postman collection so that you can see examples of the latest version of Iluma APIs in one place. In order to use these you will need to:

Open Postman (get it from here if you don't have it already)
Import the collection into your workspace. You can download it or directly import it as a link from here
Edit the collection and replace the placeholder content in the {{api-key}} variable with your own key. Note this should be your raw API key and does not need the process of adding a colon and encoding described in Authentication below as it is automatically applied when Postman generates the header

Onboarding

Flow Diagram

Onboarding Flow

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
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

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:

Manually constructing an Authorization header OR
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:

(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

Note that callbacks set up with a development API key are only used for requests made with a development API key.

2. Making your first request

Once you

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.

Note that all requests made in the development environment will hit dummy data.

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.

Note that:

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_ERROR if you provide a request payload which doesn't comply to the API specification
These headers are available in BOTH development and live environments
Requests made with these headers will NOT be charged in the live environment

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:

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

More details.

Authentication

To successfully authenticate with Iluma's API, you must use Basic Authentication with your API key as a username and no password. If you manually construct the request header to add the Authorization parameter, you must append a colon and Base 64 encode your API keys. For example if your API key is

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw

First, add a colon at the end

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw:

Finally, Base64 encode the colon appended key to get

aWx1bWFfZGV2ZWxvcG1lbnRfRlg0ZjBNNXN4RGdrNXFGeVpuazYwWmVuZ0FmQTlvMzF4M2VjZDI5dmloamM0Vmh5SjhGY2xaaEhqanc6

Iluma API is organized around REST to make it cleaner and easier to understand. All our API responses return JSON. To explore our APIs, you will need to obtain and authenticate API keys for both the development and live environments. All requests made in the development environment will hit dummy data and will not cost you anything.

Before using the API, make sure that you have registered and get your account authenticated as API requests without authentication will fail. Contact us to get started. Our sales team will process your application and send you the details you need to retrieve your API keys from the Get API Key endpoint. Then you can authenticate subsequent requests by including your secret API key in the request header. Your development and live keys determine your environment. Your Oauth Token and API keys should be kept private so do not share these.

All the API requests should be made over HTTPS instead of HTTP (all calls made over plain HTTP will fail). We’re developing libraries and plugins in the near future and if you write your own library, we would love to hear about it. Make sure you’ve completed the authentication before using our API.

Get API Key

Endpoint: Get API Key

GET https://api.iluma.ai/businesses/:business_id/api_keys?token=:token

Example Get API Key Request

curl https://api.iluma.ai/businesses/5abc/api_keys?token=123 \
    -X GET

In order to retrieve your Iluma API key, you will authenticate yourself by making a GET request to this endpoint using the Iluma business ID and Iluma OAuth token. You can get both business ID and OAuth token from our sales team after your account registration is successful.

Note that the token is single use only so you MUST save the API keys provided in the response payload when you make this request

Identity

Iluma's suite of identity products helps you to streamline your user onboarding flows with automated extraction of information from user ID documents, check whether detatils users submit to you are internally consistent and match with official Government records, and that specific identifiers are actually owned by them.

Bank Name Validator

Endpoint: Validate name on bank account and match with provided name

POST https://api.iluma.ai/v2/identity/bank_account_data_requests

Example Bank Name Validator Request

curl https://api.iluma.ai/v2/identity/bank_account_data_requests \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "given_name": "FIRA DIYANKA",
    "surname": "FEBRIYANTI",
    "reference_id": "foo123"
    }' \

The Bank Name Validator can be used to look up the name attached to bank accounts in Indonesia and run a configurable name similarity algorithm betweeen the result and the provided name. It also provides an indication whether the account is a normal bank account or not (e.g a Virtual Account), allowing you to confirm that the account is truly owned by the individual and minimising your exposure to fraud.

Bank Name Validator Request

Parameter	Description
bank_account_number	string (required) The bank account number `Note` Bank accounts will be inquired strictly as entered. If the account number requires leading 0s, you should ensure these are retained
bank_code	string (required) The bank code. See Bank Codes
given_name	string (required) The given name that will be used for name matching purposes. Please do not include honorifics.
surname	string (optional) The surname that will be used for name matching purposes
reference_id	string (optional) Your identifier for this request. Providing this may help you to reconcile requests you make to our systems
upper_threshold	number (optional) Integer, Minimum is 0, Maximum is 100. Indicate upper degree of matching tolerance
lower_threshold	number (optional) Integer, Minimum is 0, Maximum is 100. Indicate lower degree of matching tolerance

Bank Name Validator Response

Example Bank Name Validator Response (Pending bank response)

{
    "status": "PENDING",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Example Bank Name Validator Response (Account found, holder name matches)


{
    "status": "SUCCESS",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "updated": "2017-07-03T10:51:44.484Z",
    "name_matching_result": "MATCH",
    "is_normal_account": true,
    "id": "59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Example Bank Name Validator Response (Account found, holder name doesn't match)


{
    "status": "SUCCESS",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "updated": "2017-07-03T10:51:44.484Z",
    "name_matching_result": "NOT_MATCH",
    "is_normal_account": true,
    "id": "59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Example Bank Name Validator Response (Account found, holder name match is not conclusive)


{
    "status": "SUCCESS",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "updated": "2017-07-03T10:51:44.484Z",
    "name_matching_result": "UNCLEAR",
    "is_normal_account": true,
    "id": "59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Example Bank Name Validator Response (Account not found)

{
    "status": "FAILED",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "updated": "2017-03-24T08:11:07.624Z",
    "failure_reason": "BANK_ACCOUNT_NOT_FOUND_ERROR",
    "id": "59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Our name similarity algorithm will find the degree of similarity between the found name and provided name. You will see three possible categories in the response, MATCH, UNCLEAR, or NOT_MATCH.

If degree of similarity is located above upper threshold, you will get MATCH as a result.
If degree of similarity is located between upper threshold and lower threshold, you will get UNCLEAR as a result.
If degree of similarity is located below lower threshold, you will get NOT_MATCH as a result.

Note, if you set upper and lower threshold to the same number, then you will only get either MATCH or NOT_MATCH category.

Because it may take a few seconds to validate the bank account name with our sources, all results are returned to you in a callback. Be sure to have a callback URL configured for bank account data in your account (Set it with type: NAME_VALIDATOR_REQUEST). Please refer to Callback section for further details.

If the account number has not recently been queried, the synchronous HTTP response will have "status": "PENDING". For cases where we have recently queried the account, the synchronous HTTP response will contain the same response data as the callback.

Bank Name Validator Schema

Parameter	Description
bank_code	string (required) The bank code. See Bank Codes
bank_account_number	string (required) The bank account number
status	string (required) `PENDING` The name validation request is still being processed `SUCCESS` Bank account number exists `FAILED` Bank account number does not exist
updated	string (required) The last updated date of the name validation request
name_matching_result	string (optional) Only exist if status is `SUCCESS` `MATCH` The name given is > 80% match the result name `UNCLEAR` The name given is 40% - 80% match the result name `NOT_MATCH` The name given is < 40% match the result name
is_normal_account	string (optional) Only exist if status is `SUCCESS` `true` indicates a normal account (default), `false` indicates other/virtual account. This checks accounts at most major banks that issue virtual accounts: BNI, BCA, MANDIRI, BRI, CIMB, PERMATA, Maybank, NOBU Bank, Sinarmas, BTPN, BTN, Danamon, BJB, Bank Artha Graha, HSBC Indonesia. Other banks will return `true` by default
id	string (required) Unique name validator request ID
reference_id	string (optional) Your identifier for this request. Will be present only if submitted in the request payload

Bank Name Validator Errors

Error Code	Description
UNSUPPORTED_BANK_CODE_ERROR `400`	Destination bank is not supported, request is using the wrong bank code.
BANK_ACCOUNT_NUMBER_VALIDATION_ERROR `400`	Destination bank account number is invalid.

Endpoint: API Flow

The flow of the API for this endpoint are available here.

Bank Name Validator: Get by id

Endpoint: Get data request status

GET https://api.iluma.ai/v2/identity/bank_account_data_requests/:id

Example Bank Name Validator: Get by id Request

curl https://api.iluma.ai/v2/identity/bank_account_data_requests/qwertyuiop1234567890 \
    -X GET \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw

You can inquire on the status of an existing request by making a GET request to the resource using the id that is returned to you when creating the request resource. You will receive a response of the same format as shown in the response schemas above.

Bank Name Validator: Get by id Request

Parameter	Description
id	string (required) The id of the request to retrieve. This id must match the unique bank account data request id provided in our response at the time of resource creation

Example Bank Name Validator: Get by id Response (Pending bank response)

{
    "status": "PENDING",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Example Bank Name Validator Response (Account found, holder name matches)


{
    "status": "SUCCESS",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "updated": "2017-07-03T10:51:44.484Z",
    "name_matching_result": "MATCH",
    "is_normal_account": true,
    "id": "59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Example Bank Name Validator Response (Account not found)

{
    "status": "FAILED",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "updated": "2017-03-24T08:11:07.624Z",
    "failure_reason": "BANK_ACCOUNT_NOT_FOUND_ERROR",
    "id": "59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Endpoint: API Flow

The flow of the API for this endpoint are available here.

Bank Name Validator

Endpoint: Validate name on bank account and match with provided name

POST https://api.iluma.ai/v2.1/identity/bank_account_data_requests

Example Bank Name Validator Request

curl https://api.iluma.ai/v2.1/identity/bank_account_data_requests \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "given_name": "FIRA DIYANKA",
    "surname": "FEBRIYANTI",
    "reference_id": "foo123"
    }' \

The Bank Name Validator can be used to look up the name attached to bank accounts in Indonesia and run a configurable name similarity algorithm betweeen the result and the provided name. It also provides an indication whether the account is a virtual bank account or not (e.g a Normal Account), allowing you to confirm that the account is truly owned by the individual and minimising your exposure to fraud.

Bank Name Validator Request

Parameter	Description
bank_account_number	string (required) The bank account number `Note` Bank accounts will be inquired strictly as entered. If the account number requires leading 0s, you should ensure these are retained
bank_code	string (required) The bank code. See Bank Codes
given_name	string (required) The given name that will be used for name matching purposes. Please do not include honorifics.
surname	string (optional) The surname that will be used for name matching purposes
reference_id	string (optional) Your identifier for this request. Providing this may help you to reconcile requests you make to our systems
upper_threshold	number (optional) (Default: 80)Integer, Minimum is 0, Maximum is 100. Indicate upper degree of matching tolerance
lower_threshold	number (optional) (Default: 40)Integer, Minimum is 0, Maximum is 100. Indicate lower degree of matching tolerance

Bank Name Validator Response

Example Bank Name Validator Response (Pending bank response)

{
    "status": "PENDING",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Example Bank Name Validator Response (Account found, holder name matches)

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "created": "2017-07-03T10:51:44.484Z",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_5c6ba591cf3c3867d75053d7",
    "reference_id": "foo123",
    "result": {
        "is_found": true,
        "name_matching_result": "MATCH",
        "is_virtual_account": false
    },
}

Example Bank Name Validator Response (Account found, holder name doesn't match)

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "created": "2017-07-03T10:51:44.484Z",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_5c6ba591cf3c3867d75053d7",
    "reference_id": "foo123",
    "result": {
        "is_found": true,
        "name_matching_result": "NOT_MATCH",
        "is_virtual_account": false
    },
}

Example Bank Name Validator Response (Account found, holder name match is not conclusive)

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "created": "2017-07-03T10:51:44.484Z",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_5c6ba591cf3c3867d75053d7",
    "reference_id": "foo123",
    "result": {
        "is_found": true,
        "name_matching_result": "UNCLEAR",
        "is_virtual_account": false
    },
}

Example Bank Name Validator Response (Account found, dengan attribut "need_review")

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "created": "2017-07-03T10:51:44.484Z",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_5c6ba591cf3c3867d75053d7",
    "reference_id": "foo123",
    "result": {
        "is_found": true,
        "name_matching_result": "MATCH",
        "is_virtual_account": false,
        "need_review": true
    },
}

Example Bank Name Validator Response (Account not found)

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "created": "2017-07-03T10:51:44.484Z",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_5c6ba591cf3c3867d75053d7",
    "reference_id": "foo123",
    "result": {
        "is_found": false
    },
}

Example Bank Name Validator Response (Temporary network error on Iluma side, user won't be charged)

{
  "status": "FAILED",
  "bank_account_number": "1234567890",
  "bank_code": "BCA",
  "created": "2017-07-03T10:51:44.484Z",
  "updated": "2017-07-03T10:51:44.484Z",
  "id": "bknv_5c6ba591cf3c3867d75053d7",
  "failure_reason": "TEMPORARY_NETWORK_ERROR",
  "reference_id": "foo123"
}

If degree of similarity is located above upper threshold, you will get MATCH as a result.
If degree of similarity is located between upper threshold and lower threshold, you will get UNCLEAR as a result.
If degree of similarity is located below lower threshold, you will get NOT_MATCH as a result.

Note, if you set upper and lower threshold to the same number, then you will only get either MATCH or NOT_MATCH category.

Bank Name Validator Schema

Parameter	Description
bank_code	string (required) The bank code. See Bank Codes
bank_account_number	string (required) The bank account number
status	string (required) `PENDING` The name validation request is still being processed `COMPLETED` The name validation request has been processed successfully `FAILED` The name validation request has failed to be processed
updated	string (required) The last updated date of the name validation request
id	string (required) Unique name validator request ID
reference_id	string (optional) Your identifier for this request. Will be present only if submitted in the request payload
result	object (optional) Only exist if status is `COMPLETED`

Result Object Schema

Parameter	Description
is_found	boolean (required) Found the account or not
name_matching_result	string (optional) Only exist if status is `COMPLETED` `MATCH` The name given is >above upper_threshold `NOT_MATCH` The similarity between the name given and the account holder name is less than the lower_threshold `UNCLEAR` The similarity between the name given and the account holder name is between lower_threshold and upper_threshold
is_virtual_account	string (optional) Only exist if status is `COMPLETED` with is_found is `true` `true` indicates a virtual account (default), `false` indicates normal account. This checks accounts at most major banks that issue virtual accounts: BNI, BCA, MANDIRI, BRI, CIMB, PERMATA, Maybank, NOBU Bank, Sinarmas, BTPN, BTN, Danamon, BJB, Bank Artha Graha, HSBC Indonesia. Other banks will return `false` by default
need_review	string (optional) Only exist if status is `COMPLETED` with is_found is `true` `true` indicates account is found on some form of blacklists or reported fraudulent behaviour. please treat this as a warning sign and perform additional due diligence where appropriate.This feature is in beta stage and can be enabled by making a request through your account manager, our Customer Success team or writing to us at help@iluma.ai

Bank Name Validator Errors

Error Code	Description
UNSUPPORTED_BANK_CODE_ERROR `400`	Destination bank is not supported, request is using the wrong bank code.
BANK_ACCOUNT_NUMBER_VALIDATION_ERROR `400`	Destination bank account number is invalid.

Endpoint: API Flow

The flow of the API for this endpoint are available here.

Bank Name Validator: Get by id

Endpoint: Get data request status

GET https://api.iluma.ai/v2.1/identity/bank_account_data_requests/:id

Example Bank Name Validator: Get by id Request

curl https://api.iluma.ai/v2.1/identity/bank_account_data_requests/qwertyuiop1234567890 \
    -X GET \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw

Bank Name Validator: Get by id Request

Parameter	Description
id	string (required) The id of the request to retrieve. This id must match the unique bank account data request id provided in our response at the time of resource creation

Example Bank Name Validator: Get by id Response (Pending bank response)

{
    "status": "PENDING",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Example Bank Name Validator Response (Account found, holder name matches)


{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "created": "2017-07-03T10:51:44.484Z",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_5c6ba591cf3c3867d75053d7",
    "reference_id": "foo123",
    "result": {
        "is_found": true,
        "name_matching_result": "MATCH",
        "is_virtual_account": false
    },
}

Example Bank Name Validator Response (Account found, dengan attribut "need_review")

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "created": "2017-07-03T10:51:44.484Z",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_5c6ba591cf3c3867d75053d7",
    "reference_id": "foo123",
    "result": {
        "is_found": true,
        "name_matching_result": "MATCH",
        "is_virtual_account": false,
        "need_review": true
    },
}

Example Bank Name Validator Response (Account not found)

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "BCA",
    "created": "2017-07-03T10:51:44.484Z",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_5c6ba591cf3c3867d75053d7",
    "reference_id": "foo123",
    "result": {
        "is_found": false
    },
}

Example Bank Name Validator Response (Temporary network error on Iluma side, user won't be charged)

{
  "status": "FAILED",
  "bank_account_number": "1234567890",
  "bank_code": "BCA",
  "created": "2017-07-03T10:51:44.484Z",
  "updated": "2017-07-03T10:51:44.484Z",
  "id": "bknv_5c6ba591cf3c3867d75053d7",
  "failure_reason": "TEMPORARY_NETWORK_ERROR",
  "reference_id": "foo123"
}

Bank Name Validator Schema

Please refer to this section.

Endpoint: API Flow

The flow of the API for this endpoint are available here.

KTP Validator

Endpoint: Validate KTP details

POST https://api.iluma.ai/v2/identity/ktp_data_requests

Example KTP Validator Request

curl https://api.iluma.ai/v2/identity/ktp_data_requests \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
        "nik": "1234567890123456",
        "name": "FIRA DIYANKA",
        "birthplace": "JAKARTA",
        "birthdate": "01-01-1990",
        "address": "JL. SUDIRMAN NO. 3"
    }'

The KTP validator endpoint exists to help you check whether a given KTP or NIK number exists in official Indonesian Government records. In addition, if you pass in secondary details from the card we can verify whether these match with the official records.

Note that you should only use a live Production key. Development keys will return an INVALID_API_KEY error body.

KTP Validator Request

Parameter	Description
nik	string (required) The id number. NIKs must be 16 numeric characters
name	string (required) The individual's name to check against the id
birthplace	string (optional) The individual's birthplace to check against the id
birthdate	string (optional) The individual's birthdate to check against the id
address	string (optional) The individual's address to check against the id

Example KTP Validator Response

{
    "nik": "1234567890123456",
    "status": "FOUND",
    "name_match": "true",
    "birthplace_match": "true",
    "birthdate_match": "true",
    "address_match": "true"
}

KTP Validator Response

Parameter	Description
request_id	string (required) Unique ktp name validation request ID.
nik	string (required) The ID card identification number.
status	string (required) An enum indicating whether the NIK in question was found in our sources. Possible values are FOUND and NOT_FOUND.
name_match	boolean (required) A true/false indicating whether the name was a match or not.
birthplace_match	boolean (optional) A true/false indicating whether the birthplace was a match or not.
birthdate_match	boolean (optional) A true/false indicating whether the birthdate was a match or not.
address_match	boolean (optional) A true/false indicating whether the address was a match or not.

KTP Validation Errors

Error Code	Description
RATE_LIMIT_EXCEEDED `400`	You have exceeded the rate limit for this endpoint. You should exponentially back off requests until you receive a success state

Endpoint: API Flow

The flow of the API for this endpoint are available here.

CFT Individual

The CFT (Combating the Financing of Terrorism) Individual endpoint can be used to check if an individual is connected with terrorism or proliferating weapons of mass destruction based on a range databases. We currently support queries against:

Indonesian government (PPATK) provided lists for terrorism (Daftar Terduga Teroris dan Organisasi Teroris, DTTOT) and proliferation of weapons of mass destruction (Daftar Pendanaan Proliferasi Senjata Pemusnah Massal)
Office of Foreign Asset Control (OFAC) published Specially Designated Nationals (SDN) list and the consolidated non-SDN lists including Foreign Sanctions Evaders List, the List of Persons Identified as Blocked Solely Pursuant to E.O. 13599, the Non-SDN Iran Sanctions Act List, the Part 561 list, the Sectoral Sanctions Identifications List and the Non-SDN Palestinian Legislative Council List
United Nation Security Council (UNSCR) consolidated list, addressing all ongoing sanctions regimes which are currently enforced by the UN.
European Union Consolidated Financial Sanctions List (EC), addressing all ongoing sanctions regimes which are issued by the European Council. These include UN sanctions and those specific to the policy objectives of the EU.
Monetary Authority of Singapore (MAS) list.

CFT Request Schema - Individual

Endpoint: Query individual for potential matches on official cft databases

POST https://api.iluma.ai/v2/identity/cft/individual_data_requests

Example CFT Watchlist Check - Individual

curl https://api.iluma.ai/v2/identity/cft/individual_data_requests \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
        "given_name": "Kim Kyong",
        "surname": "Ok",
        "publishers": ["PPATK", "UNSCR"],
        "score_threshold": 50
    }'

We use a fuzzy match algorithm on the data you provide to rank the profiles in each of the source lists. The minimum requirement is only given_name but the confidence in positive matches will be improved when you can provide us with as many data fields as possible to enrich the search.

Parameter	Description
publishers	array (optional) An array of strings showing the lists you want to include in the search. Supported values are `UNSCR`, `OFAC`, `PPATK`, `MAS` and `EC`. If omitted, we will search all lists.
score_threshold	integer (required) The minimum score threshold below which we will filter results
given_name	string (required) The given name(s) that will be used for name matching purposes
middle_name	string (optional) Any known middle name(s) for the individual. If provided, these will increase our name matching performance
surname	string (optional) Any known surname(s) for the individual. If provided, these will increase our name matching performance
nationality	string (optional) The country of birth or citizenship of the individual. ISO 3166-2 country code
addresses	array (optional) Any known addresses (home or work) of the individual. Each address object should have the following format: *country* ISO 3166-2 country code *street_line1* Line 1 of street address e.g., building name and apartment number *street_line2* Line 2 of street address e.g., street number and name *city* City of address *province* Province of address *state* State of address *postal_code* Zip or Postal code of address *category* Address type `HOME`, `WORK` or `PROVINCIAL`. We support Provincial homes to differentiate when the individual has a week-day home address in a city and returns to a family home in the provinces on weekends or holidays
date_of_birth	string (optional) YYYY-MM-DD formatted string
phone_number	string (optional) Mobile number of the individual in E.164 format
email	string (optional) Email address of the individual

Example CFT Watchlist Response - Individual

{
    "id": "2ccdb5ff-1a2f-4cc3-9434-5fb8d3b1d11b",
    "given_name": "Kim Kyong",
    "surname": "Ok",
    "publishers": ["PPATK"],
    "results": [
        {
            "list": "LDP",
            "names": [
                "Kim Kyong Ok",
                "KIM KYONG OK"
            ],
            "score": 70,
            "publisher": "PPATK",
            "nationalities": [
                "KP"
            ],
            "record_data": {
                "pid": "north_korean_individual_33",
                "name": "KIM KYONG OK",
                "type": "INDIVIDUAL",
                "origin": "Proliferasi WMD",
                "aliases": [
                    "Kim Kyong Ok"
                ],
                "reference": "DPRKi.033",
                "nationality": "Democratic People's Republic of Korea",
                "country_code": "KP",
                "date_of_birth": "a) tahun 1937 \nb) tahun 1938",
                "place_of_birth": ""
            },
            "dates_of_birth": [
                {
                    "d": 0,
                    "m": 0,
                    "y": 1937
                },
                {
                    "d": 0,
                    "m": 0,
                    "y": 1938
                }
            ]
        }
    ]
}

CFT Response Schema - Individual

A score will be returned along with your search results to help you prioritise your due diligence. Note that we do not provide recommendations with regard to the appropriateness of any specific similarity score. This API should be one component of your arsenal and is not a substitute for undertaking appropriate due diligence. The use of this API does not limit any criminal or civil liability for any act undertaken as a result of, or in reliance on, such use.

Parameter	Description
id	string (required) Unique Response ID.
given_name	string (required) The given name of the individual submitted to the search.
middle_name	string (optional) The middle name of the individual submitted to the search.
surname	string (optional) The surname of the individual submitted to the search.
nationality	string (optional) The country of birth or citizenship of the individual submitted to the search.
addresses	array (optional) Individual's addresses submitted to the search.
date_of_birth	string (optional) Individual's date of birth submitted to the search.
phone_number	string (optional) Individual's mobile number submitted to the search.
email	string (optional) Individual's email address submitted to the search.
results	array (required) Array of result objects containing potential matches. May be an empty array.

Result Object Schema - Individual

Parameter	Description
dates_of_birth	array (optional) Array of date of birth objects according to watchlist. Each object should have the following format: *y (required)* 4 digit year *m (required)* 1-2 digit month *d (required)* 1-2 digit day Partial dates will have values of 0 for the unknown components
list	string (required) Sub-list within the publisher (e.g., `SDN` vs `Non-SDN` for OFAC)
names	array (required) Concatenation of primary known name components on the list
nationalities	array (optional) Array of ISO 3166-2 country code strings of any known nationality of the individual
publisher	string (required) Publisher of the watchlist (e.g., `OFAC`)
record_data	object (required) The unmodified record from the watchlist publisher as a JSON object. Note that we do not guarantee the consistency of the schema within this object
score	integer (required) Numeric score suggesting a degree of similarity based on the search items

Endpoint: API Flow

The flow of the API for this endpoint are available here.

CFT Entity

The CFT (Combating the Financing of Terrorism) Entity endpoint can be used to check if an entity is connected with terrorism or proliferating weapons of mass destruction based on a range databases. We currently support queries against:

Indonesian government (PPATK) provided lists for terrorism (Daftar Terduga Teroris dan Organisasi Teroris, DTTOT) and proliferation of weapons of mass destruction (Daftar Pendanaan Proliferasi Senjata Pemusnah Massal)
Office of Foreign Asset Control (OFAC) published Specially Designated Nationals (SDN) list and the consolidated non-SDN lists including Foreign Sanctions Evaders List, the List of Persons Identified as Blocked Solely Pursuant to E.O. 13599, the Non-SDN Iran Sanctions Act List, the Part 561 list, the Sectoral Sanctions Identifications List and the Non-SDN Palestinian Legislative Council List
United Nation Security Council (UNSCR) consolidated list, addressing all ongoing sanctions regimes which are currently enforced by the UN.
European Union Consolidated Financial Sanctions List (EC), addressing all ongoing sanctions regimes which are issued by the European Council. These include UN sanctions and those specific to the policy objectives of the EU.
Monetary Authority of Singapore (MAS) list.

CFT Request Schema - Entity

Endpoint: Query entity for potential matches on official cft databases

POST https://api.iluma.ai/v2/identity/cft/entity_data_requests

Example CFT Watchlist Check - Entity

curl https://api.iluma.ai/v2/identity/cft/entity_data_requests \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
        "business_name": "Yuk Tung Energy",
        "business_domicile": "SG",
        "publishers": ["PPATK", "UNSCR"],
        "score_threshold": 50
    }'

We use a similar fuzzy match algorithm to individuals but prioritise primary business identifiers instead. The minimum requirement is only business_name but the confidence in positive matches will be improved when you can provide us with as many data fields as possible to enrich the search.

Parameter	Description
publishers	array (optional) An array of strings showing the lists you want to include in the search. Supported values are `UNSCR`, `OFAC`, `PPATK`, `MAS` and `EC`. If omitted, we will search all lists.
score_threshold	integer (required) The minimum score threshold below which we will filter results
business_name	string (required) The legal or trading name of the business that will be used for search
business_domicile	string (optional) The country of registration of the business entity, if known. ISO 3166-2 country code
addresses	array (optional) Any known addresses (home or work) of the business entity. Each address object should have the following format: *country (required)* ISO 3166-2 country code *street_line1* Line 1 of street address e.g., building name and apartment number *street_line2* Line 2 of street address e.g., street number and name *city* City of address *province* Province of address *state* State of address *postal_code* Zip or Postal code of address *category* Address type `REGISTERED` or `TRADING`
date_of_registration	string (optional) YYYY-MM-DD formatted string
phone_number	string (optional) A contact phone number of the business entity in E.164 format
email	string (optional) A contact email address of the business entity

Example CFT Watchlist Response - Entity

{
    "id": "8ca9d4d4-b131-4ec3-92c0-7e9c124b919e",
    "business_name": "Yuk Tung Energy",
    "business_domicile": "SG",
    "publishers": ["UNSCR"],
    "results": [
        {
            "list": "UNSCR",
            "names": [
                "YUK TUNG ENERGY PTE LTD"
            ],
            "score": 80,
            "publisher": "UNSCR",
            "record_data": {
                "dataid": "6908689",
                "sort_key": "",
                "comments1": "Ship manager and commercial manager of the YUK TUNG, which conducted ship-to-ship transfer of refined petroleum product.",
                "list_type": {
                    "value": [
                        "UN List"
                    ]
                },
                "listed_on": "2018-03-30",
                "first_name": "YUK TUNG ENERGY PTE LTD",
                "versionnum": "1",
                "entity_alias": [
                    {
                        "quality": "",
                        "alias_name": ""
                    }
                ],
                "un_list_type": "DPRK",
                "entity_address": [
                    {
                        "city": "Singapore",
                        "street": "80 Raffles Place, #17-22 UOB Plaza",
                        "country": "Singapore",
                        "zip_code": "048624"
                    }
                ],
                "last_day_updated": {
                    "value": [
                        "2020-05-11"
                    ]
                },
                "reference_number": "KPe.075",
                "sort_key_last_mod": ""
            },
            "business_domiciles": [],
            "dates_of_registration": [
                {
                    "d": 0,
                    "m": 0,
                    "y": 0
                }
            ]
        }
    ]
}

CFT Response Schema - Entity

Parameter	Description
business_name	string (required) The name of the entity submitted to the search
business_domicile	string (optional) The domicile country submitted to the search
addresses	array (optional) The entity's addresses submitted to the search
date_of_registration	string (optional) The entity's date of registration submitted to the search
phone_number	string (optional) The contact phone number submitted to the search
email	string (optional) The contact email address submitted to the search
id	string (required) Unique Response ID
results	array (required) Array of result objects containing potential matches. May be an empty array

Result Object Schema - Entity

Parameter	Description
business_domiciles	array (optional) ISO 3166-2 country code of the business on the watchlist
dates_of_registration	array (optional) Date of registration if available on the watchlist. Each object should have the following format: *y (required)* 4 digit year *m (required)* 1-2 digit month *d (required)* 1-2 digit day Partial dates will have values of 0 for the unknown components
list	string (required) Sub-list within the publisher (e.g., `SDN` vs `Non-SDN` for OFAC)
names	array (required) Best known business name on the list
publisher	string (required) Publisher of the watchlist (e.g., `OFAC`)
record_data	object (required) The unmodified record from the watchlist publisher as a JSON object. We do not guarantee the schema within this object
score	integer (required) Numeric score suggesting a degree of similarity based on the search items

Endpoint: API Flow

The flow of the API for this endpoint are available here.