NAV undefined
undefined
bash

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:

Onboarding

Flow Diagram

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.

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

Callback

A number of our services implement a callback flow in order to maintain an acceptable http request performance and user experience. These include Bank Name Validator, NPWP Validator eWallet Validator and ID Card OCR. Callbacks will contain the completed API response (i.e., a final success or failure status once we have processed your request through all available data sources). Refer to each product documentation for further information about their respective callback response.

The various methods described in this section allow you to set, retrieve and update your callback urls. The API responses are specific to the environment you are in, so use your development API key to set callbacks for the development environment, and the live API key to set callbacks for the live environment.

All callbacks will be sent by the following IP addresses: Live environment:

Development environment:

Callback Response Schema

Unless otherwise specified, all endpoints in this section will return according to the following schema

Parameter Description
status string (required)
The status you have set for this url
url string (required)
The url that we will send callbacks to
type string (required)
The endpoint for which the callback url is configured
created string (required)
ISO 8601 Timestamp showing when this callback url was initially set
updated string (required)
ISO 8601 Timestamp showing when this callback url was last updated
id string (required)
Our unique reference ID for this callback url setting

Callback Authentication Token

Endpoint: Callback Authentication Token

GET https://api.iluma.ai/v1/callback/authentication_tokens

Example Callback Authentication Token Request

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

Make a GET request to this endpoint to return your Callback Authentication Token. This token is included in the X-CALLBACK-TOKEN header of all responses we send to the callback urls you set using the other endpoints in this section. The token allows you to verify that any callbacks you receive are coming from us. Treat the token as a secret. If you need to change the token for whatever reason, Contact us.

Example Callback Authentication Token Response

{
    "token": "47a843dfd72a9f564b6fb2e4092294d939884d62602a1a7f3679820f7ce0d0f2",
    "created": "2019-01-08T08:08:08.888Z",
    "updated": "2019-01-08T08:08:08.888Z",
    "id": "59e608887eb26d005d44aeb8"
}

Callback Authentication Token Response Schema

Parameter Description
token string (required)
The token. Treat it like a password
created string (required)
The created date of the token
updated string (required)
The last updated timestamp of the token
id string (required)
Unique callback authentication token ID

Create Callback Url

Endpoint: Create Callback Url

POST https://api.iluma.ai/v1/callback/urls

Example Create Callback Url Request

curl https://api.iluma.ai/v1/callback/urls \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
        "type": "EWALLET_ACCOUNT_VALIDATION",
        "url": "https://acme.client.com/webhook/ewallet"
    }'

Make a POST request to this endpoint to create a new callback url for the endpoint you want to set.

A test payload will be sent to your URL with the following content:

{
  "test": true
}

You need to make sure that your backend responds with HTTP status code 200 to this payload otherwise your callback URL will not be saved.

Create Callback Url Request

Parameter Description
type string (required)
The endpoint for which you want to configure a callback url. Permitted values are:
NPWP_DATA_REQUEST, NAME_VALIDATOR_REQUEST, EWALLET_ACCOUNT_VALIDATION, ID_IMAGE_OCR_REQUEST, BUSINESS_DOCUMENT_OCR_REQUEST, DOCUMENT_OCR_CAPTURE_REQUEST, BANK_NAME_VALIDATOR_DETAILS
url string (required)
The url that you want us to send callbacks to

Example Create Callback Url Response

{
    "status": "ACTIVE",
    "url": "https://acme.client.com/webhook/ewallet",
    "type": "EWALLET_ACCOUNT_VALIDATION",
    "created": "2019-01-08T08:08:08.888Z",
    "updated": "2019-01-08T08:08:08.888Z",
    "id": "59e608887eb26d005d44aeb8"
}

Create Callback Url Errors

Error Code Description
DUPLICATE_CALLBACK_URL_ERROR
400		 A callback url for this type of callback is already set. Use the PATCH method instead to update
NON_2XX_RESPONSE_ERROR
400		 Your url did not return a response in the 2XX http response code range.
REQUEST_FAILURE_ERROR
500		 We failed in making a request to your url. Check that your URL is correct

List Callback Urls

Endpoint: List Callback Url

GET https://api.iluma.ai/v1/callback/urls

Example List Callback Url Request

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

Make a GET request to this endpoint to retrieve a list of all callback urls you have set for the environment. If you have not yet set any callback urls we will return an error response.

Example List Callback Url Response

[
    {
        "status": "ACTIVE",
        "url": "https://acme.client.com/webhook/ewallet",
        "type": "EWALLET_ACCOUNT_VALIDATION",
        "created": "2019-01-08T08:08:08.888Z",
        "updated": "2019-01-08T08:08:08.888Z",
        "id": "59e608887eb26d005d44aeb8"
    },
    {
        "status": "INACTIVE",
        "url": "https://acme.client.com/webhook/name_validator",
        "type": "NAME_VALIDATOR_REQUEST",
        "created": "2019-01-08T08:08:08.888Z",
        "updated": "2019-01-08T08:08:08.888Z",
        "id": "59e608887eb26d005d44aeb8"
    }
]

List Callback Url Errors

Error Code Description
CALLBACK_URL_NOT_FOUND_ERROR
404		 You have not set any callback url for that specific type yet.

Retreive Callback Url By Type

Endpoint: Retreive Callback Url By Type

GET https://api.iluma.ai/v1/callback/urls/:type

Example Retreive Callback Url By Type Request

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

Make a GET request to this endpoint to to retrieve a specific callback url which you have previously set. Supply the type as a parameter in the url

Example Retreive Callback Url By Type Response

{
    "status": "ACTIVE",
    "url": "https://acme.client.com/webhook/name_validator",
    "type": "NAME_VALIDATOR_REQUEST",
    "created": "2019-01-08T08:08:08.888Z",
    "updated": "2019-01-08T08:08:08.888Z",
    "id": "59e608887eb26d005d44aeb8"
}

Retreive Callback Url By Type Errors

Error Code Description
CALLBACK_URL_NOT_FOUND_ERROR
404		 You have not set any callback url for that specific type yet.

Update Callback Url By Type

Endpoint: Update Callback Url By Type

PATCH https://api.iluma.ai/v1/callback/urls/:type

Example Update Callback Url By Type Request: Change Url

curl https://api.iluma.ai/v1/callback/urls/NAME_VALIDATOR_REQUEST \
    -X PATCH \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -d url="https://acme.client.com/webhook/name_validator"

Example Update Callback Url Status By Type Request: Change status

curl https://api.iluma.ai/v1/callback/urls/NAME_VALIDATOR_REQUEST \
    -X PATCH \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -d status="INACTIVE"

Make a PATCH request to update either the callback url or status of your set url. Only one of either url or status should be updated at a time. Updating the status to INACTIVE allows you to temporarily stop receiving callback for a particular service. This is useful if you're under maintenance and do not want us to keep sending out request to your url.

Example Update Callback Url By Type Response

{
    "status": "ACTIVE",
    "url": "https://acme.client.com/webhook/name_validator",
    "type": "NAME_VALIDATOR_REQUEST",
    "created": "2019-01-08T08:08:08.888Z",
    "updated": "2019-01-08T08:08:08.888Z",
    "id": "59e608887eb26d005d44aeb8"
}

Update Callback Url By Type Request

Parameter Description
status string (optional)
Status of the set callback url ACTIVE or INACTIVE
url string (optional)
The url that you want us to send callbacks to.

Update Callback Url By Type Errors

Error Code Description
CALLBACK_URL_NOT_FOUND_ERROR
404		 You have not set any callback url for that specific type yet.
NON_2XX_RESPONSE_ERROR
400		 Your url did not return a response in the 2XX http response code range.
REQUEST_FAILURE_ERROR
500		 We failed in making a request to your url.

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.

Get Available Bank Codes

Endpoint: Get available bank codes

GET https://api.iluma.ai/bank/available_bank_codes

Example Get available bank codes

curl https://api.iluma.ai/bank/available_bank_codes \
    -X GET \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw

Find the list of bank codes below for the banks we support. We support queries of accounts at 140+ banks in Indonesia, including some BPDs and BPRs. If you would like us to support a specific bank, please contact us

Bank Codes

Parameter Description
name string (required)
Bank name
code string (required)
Bank code
swift_code string (required)
Bank SWIFT code
remark string (optional)
Remarks for the bank code.

Example Get Available Bank Codes Response

[
    {
        "name": "Bank ANZ Indonesia",
        "code": "ANZ",
        "swift_code": "ANZBIDJX"
    },
    {
        "name": "Bank Artha Graha International",
        "code": "ARTHA",
        "swift_code": "ARTGIDJA"
    },
    {
        "name": "Bank Artos Indonesia",
        "code": "ARTOS",
        "swift_code": "ATOSIDJ1",
        "remark": "Deprecating in Jan 2023. Please use `JAGO` going forward"
    }
]

Get Available Bank Codes - v1.2

Endpoint: Get available bank codes

GET https://api.iluma.ai/v1.2/bank/available_bank_codes

Example Get available bank codes

curl https://api.iluma.ai/v1.2/bank/available_bank_codes \
    -X GET \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw

Find the list of bank codes below for the banks we support with country prefix. We support queries of accounts at 140+ banks in Indonesia, including some BPDs and BPRs and 40+ banks in Vietnam. If you would like us to support a specific bank, please contact us

Bank Codes

Parameter Description
name string (required)
Bank name
code string (required)
Bank code with prefix (ID_ for Indonesian bank codes and VN_ for vietnamese ones)
swift_code string (required)
Bank SWIFT code
remark string (optional)
Remarks for the bank code.

Example Get Available Bank Codes Response

[
  {
    "name": "Bank ANZ Indonesia",
    "code": "ID_ANZ",
    "swift_code": "ANZBIDJX"
  },
  {
    "name": "Bank Artha Graha International",
    "code": "ID_ARTHA",
    "swift_code": "ARTGIDJA"
  },
  {
    "name": "Bank Artos Indonesia",
    "code": "ID_ARTOS",
    "swift_code": "ATOSIDJ1",
    "remark": "Deprecating in Jan 2023. Please use `JAGO` going forward"
  },
  {
    "code": "VN_SHB",
    "name": "SHB",
    "swift_code": "",
    "remark": ""
  },
  {
    "code": "VN_SAIGONBANK",
    "name": "SAIGONBANK",
    "swift_code": "",
    "remark": ""
  },
  {
    "code": "VN_SCB",
    "name": "SCB",
    "swift_code": "",
    "remark": ""
  }
]

Bank Name Validator

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

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

Example Bank Name Validator Request

curl https://api.iluma.ai/v2.2/identity/bank_account_data_requests \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
    "bank_account_number": "1234567890",
    "bank_code": "ID_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 between 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 with the country prefix (only supports ID_ for now). See Get Available Bank Codes v1.2
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": "ID_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": "ID_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": "ID_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": "ID_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": "ID_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": "ID_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": "ID_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"
}

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.

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 with the country prefix (only supports ID_ for now). 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.2/identity/bank_account_data_requests/:id

Example Bank Name Validator: Get by id Request

curl https://api.iluma.ai/v2.2/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": "ID_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": "ID_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": "ID_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": "ID_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": "ID_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.

Bank Account Name Validator Details

Endpoint: Validate name on bank account

POST https://api.iluma.ai/v1.2/identity/bank_account_validation_details

Example Bank Name Validator Request

curl https://api.iluma.ai/v1.2/identity/bank_account_validation_details \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
    "bank_account_number": "1234567890",
    "bank_code": "ID_BCA",
    "reference_id": "foo123"
    }'

The Bank Name Validator can be used to look up the name of an account holder for bank accounts in Indonesia and Vietnam. 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
bank_code string (required)
The bank code with the country prefix. See Get Available Bank Codes v1.2
reference_id string (optional)
Your identifier for this request. Providing this may help you to reconcile requests you make to our systems

Bank Name Validator Response

Example Bank Name Validator Response (Pending bank response)

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

Example Bank Name Validator Response (Account found)

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "ID_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,
        "account_holder_name": "FIRA DIYANKA",
        "is_virtual_account": false
    },
}

Example Bank Name Validator Response (Account found) with need_review attribute

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "ID_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,
        "account_holder_name": "FIRA DIYANKA",
        "is_virtual_account": false,
        "need_review": true,
    },
}

Example Bank Name Validator Response (Account not found)

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "ID_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": "ID_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"
}

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: BANK_NAME_VALIDATOR_DETAILS). 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 with the country prefix. See Get Available Bank Codes v1.2
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
result object (optional)
Only exist if status is COMPLETED
failure_reason string (optional)
Failure reason of the request
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 schema

Parameter Description
is_found boolean (required)
Found the account or not
account_holder_name string (optional)
Only exist if status is COMPLETED with is_found is true indicates Account Holder Name
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 (ID), BCA (ID), MANDIRI (ID), BRI (ID), CIMB (ID), PERMATA (ID), Maybank (ID), NOBU Bank (ID), Sinarmas (ID), BTPN (ID), BTN (ID), Danamon (ID), BJB (ID), Bank Artha Graha (ID), HSBC Indonesia (ID). 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 Account Name Validator Details: Get by id

Endpoint: Get data request status

GET https://api.iluma.ai/v1.2/identity/bank_account_validation_details/:id

Example Bank Name Validator: Get by id Request

curl https://api.iluma.ai/v1.2/identity/bank_account_validation_details/bknv_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": "ID_BCA",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Example Bank Name Validator Response (Account found)

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "ID_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,
        "account_holder_name": "FIRA DIYANKA",
        "is_virtual_account": false
    },
}

Example Bank Name Validator Response (Account found) with need_review attribute

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "ID_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,
        "account_holder_name": "FIRA DIYANKA",
        "is_virtual_account": false,
        "need_review": true,
    },
}

Example Bank Name Validator Response (Account not found)

{
    "status": "COMPLETED",
    "bank_account_number": "1234567890",
    "bank_code": "ID_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": "ID_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.

Ewallet Validator

Endpoint: Validate details of an ewallet account

POST https://api.iluma.ai/v0/identity/ewallet_account_data_requests

Example Ewallet Account Validator Request

curl https://api.iluma.ai/v0/identity/ewallet_account_data_requests \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
        "ewallet_account_number": "08120000123",
        "ewallet_type": "GOPAY"
    }'

The Ewallet Account Validator can be used to validate the details of an account holder for major ewallets in Indonesia. We currently support GoPay, OVO, LinkAja, DANA and ShopeePay. We will be adding other sources as we gain access. Validating an ewallet account can help you to confirm destination of funds before you make a transfer into the wallet, and in some cases may assist to verify an applicant's identity.

Ewallet Account Validator Request

Parameter Description
ewallet_account_number string (required)
The ewallet account number. For ewallets which use mobile phone numbers, we support +62xxx, 08xxx with "-" or " " dividers
ewallet_type string (required)
The name of the ewallet you want to check. We currently support one of DANA, GOPAY, LINKAJA, OVO, or SHOPEEPAY

Ewallet Account Validator Response

Example Ewallet Account Validator Response (Pending eWallet response)

{
    "id": "9a48e1b2-da78-4561-8b02-f20fd89542d0",
    "ewallet_type": "MAGIC",
    "ewallet_account_number": "08111",
    "result": {},
    "status": "PENDING",
    "is_found": null,
    "updated": "2017-07-03T10:51:44.484Z"
}
{
    "id": "490a7d40-83af-4b25-8ead-da2e197be6f3",
    "ewallet_type": "MAGIC",
    "ewallet_account_number": "08222",
    "result": {
        "account_status": "ACTIVE",
        "ewallet_account_name": "FIRA DIYANKA"
    },
    "status": "COMPLETED",
    "is_found": true,
    "updated": "2020-01-03 08:21:27.110718+00:00"
}

Example Ewallet Account Validator Response (LINKAJA and GOPAY. Account found and verified - Account holder has done KYC verification)

{
    "id": "490a7d40-83af-4b25-8ead-da2e197be6f3",
    "ewallet_type": "MAGIC",
    "ewallet_account_number": "08223",
    "result": {
        "kyc_status": "VERIFIED",
        "account_status": "ACTIVE",
        "ewallet_account_name": "FIRA DIYANKA"

    },
    "status": "COMPLETED",
    "is_found": true,
    "updated": "2020-01-03 08:21:27.110718+00:00"
}

Example Ewallet Account Validator Response (LINKAJA and GOPAY. Account found and unverified. Account holder has not done KYC verification. Ewallet account name will be empty string.)

{
    "id": "490a7d40-83af-4b25-8ead-da2e197be6f3",
    "ewallet_type": "MAGIC",
    "ewallet_account_number": "08224",
    "result": {
        "kyc_status": "UNVERIFIED",
        "account_status": "ACTIVE",
        "ewallet_account_name": ""
    },
    "status": "COMPLETED",
    "is_found": true,
    "updated": "2020-01-03 08:21:27.110718+00:00"
}

Example Ewallet Account Validator Response (Account not found)

{
    "id": "cf366af5-9ea6-4d56-9f5a-8d7a9691ddf8",
    "ewallet_type": "MAGIC",
    "ewallet_account_number": "08333",
    "result": {
        "account_status": null,
        "ewallet_account_name": null
    },
    "status": "COMPLETED",
    "is_found": false,
    "updated": "2020-01-03 08:23:16.521060+00:00"
}

Because it may take a few seconds to validate the ewallet name with our sources, all results are returned to you in a callback. The callback structure will be the same as the response schema below. Be sure to have a callback URL configured for ewallet account data in your account (Set it with type: EWALLET_ACCOUNT_VALIDATION). 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.

Ewallet Account Validator Schema

Parameter Description
id string (required)
Unique ewallet account validator request ID
ewallet_type string (required)
The ewallet type. One of DANA, GOPAY, LINKAJA, OVO, or SHOPEEPAY
ewallet_account_number string (required)
The ewallet account number
result object (required)
JSON object containing all the information we can find about this account. This object will contain different content depending on the wallet type:
account_status
ACTIVE The account is active
INACTIVE The account has been closed
null The account is not found
ewallet_account_name The name associated with the eWallet account. May be a blank string if no name is available
kyc_status The verification status with the wallet provider (LINKAJA and GOPAY).
VERIFIED The account holder has done KYC verification
UNVERIFIED The account holder has not done KYC verification
status string (required)
PENDING The request is still being processed
WAITING_ON_SOURCE Your request is a duplicate and a previous request for this account is still PENDING
COMPLETED The ewallet validation request has been completed
is_found string (required)
Whether the ewallet account is found
updated string (required)
The last updated date of the ewallet account validation request in UTC ISO date format

Ewallet Account Validator Errors

Error Code Description
UNSUPPORTED_EWALLET_TYPE_ERROR
400		 This ewallet type is not currently supported. Permitted ewallet accounts are shown in the request schema above
INVALID_ACCOUNT_NUMBER_FORMAT
400		 This ewallet account number has invalid format.

Endpoint: API Flow

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

Ewallet Validator: Get by id

Endpoint: Get data request status

GET https://api.iluma.ai/v0/identity/ewallet_account_data_requests/:id

Example Ewallet Validator: Get by id request

curl https://api.iluma.ai/v0/identity/ewallet_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 recieve a response of the same format as shown in the response schemas above.

Ewallet Validator: Get by id Request

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

Example Ewallet Validator: Get by id Response

{
    "id": "490a7d40-83af-4b25-8ead-da2e197be6f3",
    "ewallet_type": "MAGIC",
    "ewallet_account_number": "08222",
    "result": {
        "account_status": "ACTIVE",
        "ewallet_account_name": "FIRA DIYANKA"
    },
    "status": "COMPLETED",
    "is_found": true,
    "updated": "2020-01-03 08:21:27.110718+00:00"
}

Endpoint: API Flow

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

NPWP Validator

Endpoint: Validate NPWP

POST https://api.iluma.ai/v1/identity/npwp_data_requests

Example NPWP Validator Request

curl https://api.iluma.ai/v1/identity/npwp_data_requests \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{ "account_number": "123456789012345" }'

NPWP Validator can be used to look up the account holder name of a tax identification number (NPWP) in Indonesia. We cover both businesses and individuals.

Supported country: 🇮🇩

NPWP Validator Request

Parameter Description
scope string (optional)
Scope of validation request.NPWP_VALIDATOR request using account number and NPWP_VALIDATOR_ADVANCE request using identity card number. Enum: NPWP_VALIDATOR, NPWP_VALIDATOR_ADVANCE. Default value: NPWP_VALIDATOR.
account_number string (optional)
15 digits NPWP number. Can be 15 digits or in a 12.345.678.9-012.345 format. Mandatory when scope is NPWP_VALIDATOR.
id_card_number string (optional)
Identity card number. Mandatory when scope is NPWP_VALIDATOR_ADVANCE.

NPWP Validator Response

If the account number has not recently been queried, the response will have "status": "PENDING", and you will be a sent a callback when the request completes. Be sure to have a callback URL configured for NPWP data in your account (Set it with type: NPWP_DATA_REQUEST). Please refer to Callback section for further details.

Example NPWP Validator Response (Pending)

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "created": "2017-07-03T10:51:44.484Z",
  "updated": "2017-07-03T10:51:44.484Z",
  "account_number": "000000000000000",
  "status": "PENDING"
}

Example NPWP Validator Response (Account found)

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "created": "2017-07-03T10:51:44.484Z",
  "updated": "2017-07-03T10:51:44.484Z",
  "account_number": "999999999999999",
  "status": "COMPLETED",
  "is_found": true,
  "result":{
    "account_name": "FIRA DIYANKA"
  }
}

Example NPWP Validator Response (Account not found)

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "created": "2017-07-03T10:51:44.484Z",
  "updated": "2017-07-03T10:51:44.484Z",
  "account_number": "111111111111111",
  "status": "COMPLETED",
  "is_found": false,
  "result":{}
}

Example NPWP Validator Using Identity Card Number Response (Failed)

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "created": "2017-07-03T10:51:44.484Z",
  "updated": "2017-07-03T10:51:44.484Z",
  "account_number": "444444444444444",
  "status": "FAILED",
  "failure_reason": "TEMPORARY_NETWORK_ERROR",
  "is_found": false,
  "result":{}
}

Example NPWP Validator Using Identity Card Number Response (Pending)

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "created": "2017-07-03T10:51:44.484Z",
  "updated": "2017-07-03T10:51:44.484Z",
  "id_card_number": "999999999999999",
  "status": "PENDING"
}

Example NPWP Validator Using Identity Card Number Response (Account found)

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "created": "2017-07-03T10:51:44.484Z",
  "updated": "2017-07-03T10:51:44.484Z",
  "id_card_number": "999999999999999",
  "status": "COMPLETED",
  "is_found": true,
  "result":{
    "account_name": "FIRA DIYANKA"
  }
}

Example NPWP Validator Using Identity Card Number Response (Account not found)

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "created": "2017-07-03T10:51:44.484Z",
  "updated": "2017-07-03T10:51:44.484Z",
  "id_card_number": "999999999999999",
  "status": "COMPLETED",
  "is_found": false,
  "result":{}
}

Example NPWP Validator Using Identity Card Number Response (Failed)

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "created": "2017-07-03T10:51:44.484Z",
  "updated": "2017-07-03T10:51:44.484Z",
  "id_card_number": "444444444444444",
  "status": "FAILED",
  "failure_reason": "TEMPORARY_NETWORK_ERROR",
  "is_found": false,
  "result":{}
}

NPWP Validator Schema

Parameter Description
id string (required)
Unique NPWP request ID
created string (required)
The created date of the NPWP request
updated string (required)
The last updated date of the NPWP request
account_number string (optional)
The NPWP account number you supplied when scope is NPWP_VALIDATOR
id_card_number string (optional)
The identity card number you supplied when scope is NPWP_VALIDATOR_ADVANCE
status string (required)
PENDING The NPWP request is still being processed
WAITING_ON_SOURCE The NPWP request is still being processed by our source
COMPLETED The NPWP request has completed processing
FAILED The NPWP request has failed processing due to one or more reasons. Please refer to failure_reason for more information.
failure_reason string (optional)
See NPWP Validator Failure Reasons
is_found boolean (required)
true The NPWP account number is valid and has been found.
false This NPWP account number is invalid or is not found.
result object (required)
JSON object containing all the information we can find about this account:
account_name
NPWP account holder name. May be null or blank

NPWP Validator Failure Reasons

Failure Reason Description
TEMPORARY_NETWORK_ERROR An upstream source returned a temporary error. You may retry this request.
MULTIPLE_NPWP_ACCOUNT_ERROR Found more than 1 NPWP account belongs to the provided id_card_number.
Please use the self serve facility to change the data in ereg application or DJP online.

Endpoint: API Flow

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

Magic Replies

Please refer to this section

NPWP Validator: Get by id

Endpoint: Get data request status

GET https://api.iluma.ai/v1/identity/npwp_data_requests/:id

Example NPWP Validator: Get by id request

curl https://api.iluma.ai/v1/identity/npwp_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 recieve a response of the same format as shown in the response schemas above.

NPWP Validator: Get by id Request

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

Example NPWP Validator: Get by id Response

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "created": "2017-07-03T10:51:44.484Z",
  "updated": "2017-07-03T10:51:44.484Z",
  "account_number": "999999999999999",
  "status": "COMPLETED",
  "is_found": true,
  "result":{
    "account_name": "FIRA DIYANKA"
  }
}

Endpoint: API Flow

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

Individual Authentication

Endpoint: ID Data Verification

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

Example ID Data Verification Request

curl https://api.iluma.ai/v2/identity/id_card_data_verifications \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -F 'id_card_number="3275031210930027"' \
    -F 'name="penito kristian"' \
    -F 'birthdate="12-10-1991"' \

The individual authentication endpoint exists to help you check whether a given Indonesian Identity card number (NIK) exists in the official records of the Indonesian government and checks whether the name and birthdate provided in the parameter matches.

Supported country: 🇮🇩

Individual Authentication Request

Content type: form-data

Parameter Description
id_card_number string (required)
The Indonesian identity card number (NIK)
name string (required)
The full name of the individual as shown on the ID card
Min - 2 characters, Max - 100 characters
birthdate string (required)
Date of birth as shown on the ID card
Format DD-MM-YYYY string
birthplace string (optional)
The city of birth as shown on the ID card
name_threshold number (optional)
Determines the name similarity threshold that would qualify for a match. Default 90

Individual Authentication Response

Example ID Data Verification Response - Success (Found)

{
  "id": "idvr_c2b7a96a-9dc2-491e-b274-71c84b6e25d1",
  "created": "2022-06-29T08:18:43.529Z",
  "updated": "2022-06-29T08:18:43.529Z",
  "id_card_number": "3275031210930027",
  "name": "penito kristian",
  "name_threshold": 90,
  "birthdate": "12-10-1990",
  "birthplace": "Surabaya",
  "status": "COMPLETED",
  "id_card_number_found": true,
  "results": {
    "name": {
      "match": true
    },
    "birthdate": {
      "match": true
    },
    "birthplace": {
      "match": true
    }
  }
}

Example ID Data Verification Response - Success (Not Found)

{
  "id": "idvr_c2b7a96a-9dc2-491e-b274-71c84b6e25d1",
  "created": "2022-03-21T12:24:42.480Z",
  "updated": "2022-03-21T12:24:42.480Z",
  "id_card_number": "3275031210930021",
  "name": "penito kristian",
  "birthdate": "12-10-1990",
  "birthplace": "Surabaya",
  "status": "COMPLETED",
  "id_card_number_found": false
}

Example ID Data Verification Response - Failure

{
  "id": "idvr_c2b7a96a-9dc2-491e-b274-71c84b6e25d2",
  "created": "2022-03-21T12:24:42.480Z",
  "updated": "2022-03-21T12:24:42.480Z",
  "id_card_number": "3275031210930021",
  "name": "penito kristian",
  "birthdate": "12-10-1990",
  "birthplace": "Surabaya",
  "status": "FAILED",
  "failure_reason": "TEMPORARY_NETWORK_ERROR"
}

You will receive a JSON response with a reference id on submitting the POST request.

ID Data Verification Schema

Parameter Description
id string (required)
A unique identifier of the request
created string (required)
The receipt date of the request. ISO8601 timestamp in UTC
updated string (required)
The last updated date of the request. ISO8601 timestamp in UTC
id_card_number string (required)
The national identity card number as per the KTP card
name string (required)
Name of the individual as per the KTP card
birthdate string (optional)
Date of birth as shown on the KTP card
birthplace string (optional)
Date of birth as shown on the KTP card
id_card_number_found boolean (optional)
Present if status is COMPLETED. Whether the NIK was found in Dukcapil’s database
results object (optional)
The validation results. Present if status is COMPLETED and id_card_number_found true
failure_reason string (optional)
The reason for the failure. Possible values: TEMPORARY_NETWORK_ERROR

Result Object Schema

Parameter Description
name.match boolean (required)
If the name similarity passes the name_threshold, this parameter will return true (and false otherwise)
birthdate.match boolean (optional)
If the birthdate matches, this parameter will return true (and false otherwise)
birthplace.match boolean (optional)
If the birthplace matches, this parameter will return true (and false otherwise)

ID Data Verification Errors

Error Code Description
API_VALIDATION_ERROR
400		 The request payload does not match what was specified. Missing form fields are provided in the response payload.
INVALID_API_KEY
401		 API key format is invalid
API_KEY_IS_NOT_LIVE_ERROR
403		 The API key does not have the permission to perform this request
RATE_LIMIT_EXCEEDED
429		 Rate Limit hit. See errors.
SERVER_ERROR
500		 The service is down or other errors

Endpoint: API Flow

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

Individual Photo Authentication

Endpoint: ID Card Verification

POST https://api.iluma.ai/v1/identity/id_card_verifications

Example ID Card Verification Request

curl https://api.iluma.ai/v1/identity/id_card_verifications \
    -X POST \
    -u <your-api-key>: \
    -F 'name="penito kristian"' \
    -F 'id_card_number="3275031210930027"' \
    -F 'birthdate="12-10-1991"' \
    -F 'phone="081234567890"' \
    -F 'selfie=@"/path/to/selfie.png"'' \
    -F 'ktp_image=@"/path/to/ktp_image.png"''
    -F 'email="test@test.com"' \

The Individual Photo Authentication endpoint exists to help you check if a given Indonesian Identity card number (NIK) exists in the official records of the Indonesian government and checks if the selfie matches the photo in offial records.

Supported country: 🇮🇩

ID Card Verification Request

Content type: form-data

Parameter Description
name string (required)
The full legal name of the individual shown on the ID card
Min - 2 characters, Max - 100 characters
id_card_number string (required)
The national identity card number shown on the ID card
birthdate string (required)
Date of birth as shown on the ID card
Format DD-MM-YYYY string
selfie file (required)
Selfie image of the individual to check against the image that Dukcapil holds for the supplied NIK
Supported mime types: image/jpeg, image/png. Maximum file size: 2 MB. Minimum file size: 100KB, 500x500 pixels
phone string (optional)
Phone Number Associated with ID Card number. Supported Formats: (+62xxx, 08xxx)
ktp_image file (required)
ID image of the individual to check against the image that Dukcapil holds for the supplied NIK
Supported mime types: image/jpeg, image/png. Maximum file size: 2 MB. Minimum file size: 100KB, 500x500 pixels
email string (optional)
Email address of the individual to check against the registered email in Dukcapil

ID Card Verification Response

Example ID Card Verification Response - Completed (Verified)

{
    "id": "idvr_c2b7a96a-9dc2-491e-b274-71c84b6e25d1",
    "created": "2022-03-21T12:24:42.480Z",
    "updated": "2022-03-21T12:24:42.480Z",
    "id_card_number": "3275031210930027",
    "name": "penito kristian",
    "birthdate": "12-10-1990",
    "phone": "081234567890",
    "email": "test@test.com",
    "status": "COMPLETED",
    "is_verified": true,
}

Example ID Card Verification Response - Completed (Unverified)

{
    "id": "idvr_c2b7a96a-9dc2-491e-b274-71c84b6e25d1",
    "created": "2022-03-21T12:24:42.480Z",
    "updated": "2022-03-21T12:24:42.480Z",
    "id_card_number": "3275031210930027",
    "name": "penito kristian",
    "birthdate": "12-10-1990",
    "phone": "081234567890",
    "email": "test@test.com",
    "status": "COMPLETED",
    "is_verified": false,
    "failure_reason": "Selfie Not Match"
}

Example ID Card Verification Response - Failure

{
    "id": "idvr_c2b7a96a-9dc2-491e-b274-71c84b6e25d1",
    "created": "2022-03-21T12:24:42.480Z",
    "updated": "2022-03-21T12:24:42.480Z",
    "id_card_number": "3275031210930027",
    "name": "penito kristian",
    "birthdate": "12-10-1990",
    "phone": "081234567890",
    "email": "test@test.com",
    "status": "FAILED",
    "is_verified": false,
    "failure_reason": "TEMPORARY_NETWORK_ERROR"
}

You will receive a JSON response with a reference id on submitting the POST request.

ID Card Verification Schema

Parameter Description
id string (required)
A unique identifier of the request
created string (required)
The receipt date of the request. ISO8601 timestamp in UTC
updated string (required)
The last updated date of the request. ISO8601 timestamp in UTC
id_card_number string (required)
The national identity card number as per the KTP card
name string (required)
Name of the individual as per the KTP card
birthdate string (required)
Date of birth as shown on the KTP card
email string (optional)
Email address of the individual
phone string (optional)
Phone Number of the individual. Supported Formats: (+62xxx, 08xxx)
is_verified boolean (required)
Whether the details given was verified in Dukcapil’s database
failure_reason string (optional)
The reason for the failure. Possible values: TEMPORARY_NETWORK_ERROR and others

Endpoint: API Flow

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

Magic Replies

Please refer to this section

ID Card Verification Errors

Error Code Description
API_VALIDATION_ERROR
400		 The request payload does not match what was specified. Missing form fields are provided in the response payload.
INVALID_API_KEY
401		 API key format is invalid
API_KEY_IS_NOT_LIVE_ERROR
403		 The API key does not have the permission to perform this request
FILE_TOO_LARGE
413		 Selfie image too large
FILE_TOO_SMALL
413		 Selfie image too small
UNSUPPORTED_CONTENT_TYPE
415		 Selfie image is of wrong file type
RATE_LIMIT_EXCEEDED
429		 Rate Limit hit. See errors.
SERVER_ERROR
500		 The service is down or other errors

Failure Reason List

failure_reason Description
NIK is Invalid Inputted NIK is invalid
Selfie is Invalid Inputted Selfie is invalid
NIK not found NIK is not found
Full Name Not Match Full Name is not match
DOB Not Match Date of Birth is not match
Selfie Not Match, Score More Than 30, Less Than 70 Selfie is not match with certain degree of matching
Selfie Not Match, Score More Than 0, Below 30 Selfie is not match with certain degree of matching
Full Name Not Match & DOB Not Match Both parameters are not match
Full Name Not Match & Selfie Not Match Both parameters are not match
DOB Not Match & Selfie Not Match Both parameters are not match
Full Name Not Match & DOB Not Match & Selfie Not Match The parameters are not match
TEMPORARY_NETWORK_ERROR Temporary Network Error

Guidance

To minimize failures due to image verification issues, it is recommended to guide end-users to take their selfie and ID card images in such a way that:

The image above is recommended.

This image is still acceptable as long as the ID card is larger than the background.

ID Card OCR

Endpoint: Extract ID card details using OCR

POST https://api.iluma.ai/v1/identity/id_card_images

Example ID Card OCR Request

curl https://api.iluma.ai/v1/identity/id_card_images \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -F 'type="indonesia_ktp"' \
    -F 'image=@"/path/to/file.png"'
    -F 'reference_id="foo123"'

The ID card OCR endpoint exists to help you extract text and images from a photograph of an official Indonesian Government ID card. We recommend supplying photos which are in a standard landscape orientation, square-on to the camera and clearly focused for maximum effectiveness. We will clean and process any image you supply but the best method to ensure accurate OCR output is if you can control capture quality when obtaining the raw images.

Supported country: 🇮🇩

ID Card OCR Request

Content type: multi-part/form

Parameter Description
type string (required)
The type of ID being queried.
We currently support passport, indonesia_ktp (NIK) and npwp_card (NPWP) only
image file (required)
An ID photo of mime type image/png, image/bmp, image/jpeg. Maximum file size 2MB
reference_id string (optional)
Your identifier for this request. Providing this may help you to reconcile requests you make to our systems

ID Card OCR Response

Example ID Card OCR Response - Pending

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "data": {},
  "status": "PENDING",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "indonesia_ktp",
  "reference_id":"foo123"
}

Example ID Card OCR Response - Completed
NIK Example

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "data": {
    "idNumber": "1234567890123456",
    "name": "FIRA DIYANKA",
    "religion": "KRISTEN",
    "gender": "LAKI-LAKI",
    "birthPlaceBirthday": "JAKARTA,17-10-1975",
    "province": "JAWA TENGAH",
    "city": "KABUPATEN JEPARA",
    "district": "KELING",
    "village": "KELET",
    "rtrw": "015/004",
    "address":"JL. VETERAN GG. GARUDA NO.73D/34",
    "occupation": "KARYAWAN SWASTA",
    "expiryDate": "12-08-2016",
    "nationality": "WNI",
    "maritalStatus":"BELUM KAWIN"
  },
  "status": "COMPLETED",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "indonesia_ktp",
  "reference_id":"foo123"
}

NPWP Example

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "data": {
        "npwpId": "123456789123000",
        "address": null,
        "idNumber": null,
        "npwpName": "FIRA DIYANKA",
        "registrationOffice": null
  },
  "status": "COMPLETED",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "npwp_card",
  "reference_id":"foo123"
}

Passport Example

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "data": {
        "gender": "Female",
        "country": "UNITED STATES OF AMERICA",
        "surname": "TRAVELER",
        "given_name": "HAPPY",
        "is_tampered": true,
        "date_of_birth": "1965-02-05T00:00:00.000Z",
        "date_of_issue": "2020-10-15T00:00:00.000Z",
        "date_of_expiry": "2030-10-14T00:00:00.000Z",
        "place_of_birth": "WASHINGTON, D.C.,U.S.A.",
        "passport_number": "E00007734",
        "issuing_authority": ""
  },
  "status": "COMPLETED",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "passport",
  "reference_id":"foo123"
}

Example ID Card OCR Response - Completed with Unreadable ID Data

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "data": {},
  "status": "COMPLETED",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "indonesia_ktp",
  "reference_id":"foo123"
}

Example ID Card OCR Response - Failure

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "status": "FAILED",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "indonesia_ktp",
  "failure_reason": "IMAGE_RECOGNIZE_ERROR",
  "reference_id":"foo123"
}

You will receive a JSON response with an id on submitting the POST request. Because it may take a few seconds to upload and process the image file, all results are returned to you in a callback. Be sure to have a callback URL configured for ID card OCR in your account (Set it with type: ID_IMAGE_OCR_REQUEST). Please refer to Callback section for further details.

ID Card OCR Schema

Parameter Description
id string (required)
A unique identifier of the id card image request for use in later API calls
data json (optional)
The text content we have extracted from the ID card
status string (required)
The status of the OCR processing attempt
created string (required)
The receipt date of the OCR request. ISO8601 timestamp
updated string (required)
The last updated date of the OCR request. ISO8601 timestamp
type string (required)
The type of OCR request.
failure_reason string (optional)
The reason for the failure
reference_id string (optional)
The reference id of the user input

ID Card OCR Errors

Error Code Description
API_VALIDATION_ERROR
400		 The request payload does not match what was specified. Missing form fields are provided in the response payload.
FILE_TOO_LARGE
413		 The image is too large (> 2 MB, > 4096x4096 px. Please reduce image size before retrying.
UNSUPPORTED_CONTENT_TYPE
415		 The file is in an unsupported format.
Only PNG, JPG, BMP are supported

Endpoint: API Flow

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

ID Card OCR: Get by id

Endpoint: Get data request status

GET https://api.iluma.ai/v1/identity/id_card_images/:id

Example ID Card OCR: Get by id Request

curl https://api.iluma.ai/v1/identity/id_card_images/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.

ID Card OCR: Get by id Request

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

Example ID Card OCR Response - Pending

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "data": {},
  "status": "PENDING",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "indonesia_ktp",
  "reference_id":"foo123"
}

Example ID Card OCR Response - Completed
NIK Example

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "data": {
    "idNumber": "1234567890123456",
    "name": "FIRA DIYANKA",
    "religion": "KRISTEN",
    "gender": "LAKI-LAKI",
    "birthPlaceBirthday": "JAKARTA,17-10-1975",
    "province": "JAWA TENGAH",
    "city": "KABUPATEN JEPARA",
    "district": "KELING",
    "village": "KELET",
    "rtrw": "015/004",
    "address":"JL. VETERAN GG. GARUDA NO.73D/34",
    "occupation": "KARYAWAN SWASTA",
    "expiryDate": "12-08-2016",
    "nationality": "WNI",
    "maritalStatus":"BELUM KAWIN"
  },
  "status": "COMPLETED",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "indonesia_ktp",
  "reference_id":"foo123"
}

NPWP Example

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "data": {
        "npwpId": "123456789123000",
        "address": null,
        "idNumber": null,
        "npwpName": "FIRA DIYANKA",
        "registrationOffice": null
  },
  "status": "COMPLETED",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "npwp_card",
  "reference_id":"foo123"
}

Passport Example

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "data": {
        "gender": "Female",
        "country": "UNITED STATES OF AMERICA",
        "surname": "TRAVELER",
        "given_name": "HAPPY",
        "is_tampered": true,
        "date_of_birth": "1965-02-05T00:00:00.000Z",
        "date_of_issue": "2020-10-15T00:00:00.000Z",
        "date_of_expiry": "2030-10-14T00:00:00.000Z",
        "place_of_birth": "WASHINGTON, D.C.,U.S.A.",
        "passport_number": "E00007734",
        "issuing_authority": ""
  },
  "status": "COMPLETED",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "passport",
  "reference_id":"foo123"
}

Example ID Card OCR Response - Completed with Unreadable ID Data

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "data": {},
  "status": "COMPLETED",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "indonesia_ktp",
  "reference_id":"foo123"
}

Example ID Card OCR Response - Failure

{
  "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
  "status": "FAILED",
  "created": "2021-02-19T06:50:25.619Z",
  "updated": "2021-02-19T06:50:25.619Z",
  "type": "indonesia_ktp",
  "failure_reason": "IMAGE_RECOGNIZE_ERROR",
  "reference_id":"foo123"
}

ID Card OCR: Get by Reference id

Endpoint: Get data request status

GET https://api.iluma.ai/v1/identity/id_card_images?reference_id=:reference_id&limit=:limit&after_id=:after_id

Example ID Card OCR: Get by Reference id Request

curl https://api.iluma.ai/v1/identity/id_card_images?reference_id=foo123
    -X GET \
    -u iluma_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:

You can inquire on the status of an existing request by making a GET request to the resource using the Reference 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.

ID Card OCR: Get by Reference id Request

Parameter Description
reference_id string (required)
The reference_id of the request to retrieve. This reference_id is provided by the user
limit integer (optional)
The limit is number of records retrieved from the database. Default value is 10 records.
after_id string (optional)
This is provided from the response when there is excess records left based on the specified limit. This is to allow retrieval of your next set of records on the same Reference id.

ID Card OCR Get by Reference id Response Schema

Example of Get by Reference ID - Success Response 

{
  "data":[{
    "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
    "data": {
      "idNumber": "1234567890123456",
      "name": "FIRA DIYANKA",
      "religion": "KRISTEN",
      "gender": "LAKI-LAKI",
      "birthPlaceBirthday": "JAKARTA,17-10-1975",
      "province": "JAWA TENGAH",
      "city": "KABUPATEN JEPARA",
      "district": "KELING",
      "village": "KELET",
      "rtrw": "015/004",
      "address":"JL. VETERAN GG. GARUDA NO.73D/34",
      "occupation": "KARYAWAN SWASTA",
      "expiryDate": "12-08-2016",
      "nationality": "WNI",
      "maritalStatus":"BELUM KAWIN"
    },
    "status": "COMPLETED",
    "created": "2021-02-19T06:50:25.619Z",
    "updated": "2021-02-19T06:50:25.619Z",
    "type": "indonesia_ktp",
    "reference_id":"foo123"
  }],
  "has_more": false,
  "links": [
      {
          "href": "/v1/identity/id_card_images?reference_id=foo123",
          "rel": "first",
          "method": "GET"
      },
      {
          "href": "/v1/identity/id_card_images?reference_id=foo123",
          "rel": "self",
          "method": "GET"
      }
  ]
}

Example of Get by Reference ID - Success Response with limit and after_id on response object 

{
  "data":[{
    "id": "f95ae802-4d96-4066-ada7-fe9487d4ca5e",
    "data": {
      "idNumber": "1234567890123456",
      "name": "FIRA DIYANKA",
      "religion": "KRISTEN",
      "gender": "LAKI-LAKI",
      "birthPlaceBirthday": "JAKARTA,17-10-1975",
      "province": "JAWA TENGAH",
      "city": "KABUPATEN JEPARA",
      "district": "KELING",
      "village": "KELET",
      "rtrw": "015/004",
      "address":"JL. VETERAN GG. GARUDA NO.73D/34",
      "occupation": "KARYAWAN SWASTA",
      "expiryDate": "12-08-2016",
      "nationality": "WNI",
      "maritalStatus":"BELUM KAWIN"
    },
    "status": "COMPLETED",
    "created": "2021-02-19T06:50:25.619Z",
    "updated": "2021-02-19T06:50:25.619Z",
    "type": "indonesia_ktp",
    "reference_id":"foo123"
  }],
  "has_more": true,
  "links": [
      {
          "href": "/v1/identity/id_card_images?reference_id=foo123",
          "rel": "first",
          "method": "GET"
      },
      {
          "href": "/v1/identity/id_card_images?reference_id=foo123&limit=1",
          "rel": "self",
          "method": "GET"
      },
      {
            "rel": "next",
            "href": "/v1/identity/id_card_images?reference_id=foo123&limit=1&after_id=764d6583-6866-490d-b6c3-98f3de797d1b",
            "method": "GET"
      }
  ]
}

Example ID Card OCR Response - Reference id not found

{
  "data":[],
  "has_more":false,
  "links": [
        {
            "href": "/v1/identity/id_card_images?reference_id=foo456",
            "rel": "first",
            "method": "GET"
        },
        {
            "href": "/v1/identity/id_card_images?reference_id=foo456",
            "rel": "self",
            "method": "GET"
        }
    ]
}
Parameter Description
data array (required)
Array of ID Card OCR Objects returned by the query. May be an empty array
has_more boolean (required)
Indicates whether there are more items to be queried with after_id of the last item from current result
links array (required)
Array of links used to process the request. It may include the link for the next set of records if has_more is set to true

Endpoint: API Flow

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

Face Comparison

Endpoint: Compare the similarity of two faces

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

Example Face Comparison Request

curl https://api.iluma.ai/v2/identity/face_comparisons \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    --form 'image_one=@"image_one.jpg"' \
    --form 'image_one=@"image_two.jpg"'

The Face Comparison endpoint exists to help you validate whether two photos are of the same person, such as a photo of their face (selfie) and a photo of their ID card. We will recognise the photo within the ID card, extract it and compare this to the second image. We split this into two images as we strongly advise against performing this check using a single photo for example, of a user holding their ID card, as typical photo capture by end-users results in ID cards which are small and poorly focused, reducing accuracy of further processing.

Face Comparison Request

Parameter Description
image_one file (required)
Image of the individual to use for face comparison
Supported mime types: image/jpeg, image/png, and image/bmp. Max Size 2MB.
image_two file (required)
Image of the individual to use for face comparison
Supported mime types: image/jpeg, image/png, and image/bmp. Max Size 2MB.

Face Comparison Response

Example Face Comparison Response - Success

{
  "status": "COMPLETED",
  "match_percentage": 97.5,
  "id": "5ba359137f94918d2b0cb8bb"
}

Example Face Comparison Response - Failure

{
  "status": "FAILED",
  "failure_reason": "No face detected in image",
  "id": "5ba359137f94918d2b0cb8bb"
}

You will receive a JSON response with a reference id on submitting the POST request.

Face Comparison Schema

Parameter Description
status string (required)
The status of the Face Comparison attempt
match_percentage number (optional)
The percentage similarity of the match
failure_reason string (optional)
Reason for failed result
id string (required)
A unique identifier of the request

Face Comparison Errors

Error Code Description
API_VALIDATION_ERROR
400		 The response may be due to any of the following reasons: the image is in an unsupported format (only PNG, JPG/JPEG, BMP are supported), if any of the image is above 2MB, and if request is missing required parameters

Endpoint: API Flow

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

Face Liveness Check

This endpoint will let you submit a selfie to perform a passive face liveness check on.

Endpoint: Perform liveness checks

POST https://api.iluma.ai/v0/identity/liveness_checks

Example Request - Perform liveness checks

curl https://api.iluma.ai/v0/identity/liveness_checks \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -F 'reference_id="test_reference_id"' \
    -F 'image=@"/path/to/file.png"'
Parameter Description
reference_id string (optional)
The client’s unique ID for this request
selfie file (required)
Selfie image of the individual. Supported mime types: image/jpeg, image/png. Maximum file size: 500KB. Minimum file size: 100KB, 400x400 pixels

Example Response

{
  "id": "lvck_00df1710-8b06-4cd1-a32c-8f2b39cad6fe",
  "created": "2022-03-25T05:56:14.193Z",
  "updated": "2022-03-25T05:56:20.827Z",
  "reference_id": "test",
  "status": "COMPLETED",
  "confidence": 99,
  "is_live": true,
  "result": {
    "are_eyes_open": true,
    "is_face_cropped": false,
    "face_mask_detected": false,
    "multiple_faces_detected": true
  }
}

Response Schema

Parameter Description
id string (required)
A unique identifier of the document request for use in later API calls
reference_id string (required)
The client’s unique ID for this request. Will return null if NOT provided by the client in the request body
created string (required)
The receipt date of the OCR request. ISO8601 timestamp in UTC
updated string (required)
The last updated date of the OCR request. ISO8601 timestamp in UTC
status string (required)
Possible values: COMPLETED - processing completed successfully, FAILED - processing interrupted and/or fail at any stage
failure_reason string (optional)
The reason for the failure. Possible values: TEMPORARY_NETWORK_ERROR
is_live boolean (required)
Liveness check result. Present if status is COMPLETED
confidence number (required)
Confidence score on is_live flag. Present if status is COMPLETED
result object (optional)
Present if status is COMPLETED

Result Object Schema

Parameter Description
are_eyes_open boolean (required)
This parameter will detect if the eyes of the person clicking the selfie are open.
is_face_cropped boolean (required)
Enum: true or false. Whether face cropped in the image.
face_mask_detected boolean (required)
Enum: true or false. Whether a face mask was detected in the image
multiple_faces_detected boolean (required)
Enum: true or false. "true" when multiple prominent faces were found in the selfie.

Endpoint: API Flow

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

Business Document OCR

Endpoint: Extract Business Document OCR

POST https://api.iluma.ai/v1/identity/document_ocr_requests

Example Business Document OCR Request

curl --location --request POST 'https://api.iluma.ai/v1/identity/document_ocr_requests' \
    --form 'image=@"SK Menkeh .pdf"' \
    --form 'reference_id="foo123"' \
    --form 'type="BUSINESS_REGISTRATION"' \
    --form 'country="ID"' \
    --form 'document_name="SK_MENKEH"'

The Business Document OCR endpoint exists to help you extract text and images from a file of an official Business Document. We recommend supplying photos which are in a standard landscape orientation, square-on to the camera and clearly focused for maximum effectiveness. We will clean and process any image or file you supply but the best method to ensure accurate OCR output is if you can control capture quality when obtaining the raw images.

Business Document OCR Request

Requests should be of type multi-part/form with the following content

Parameter Description
reference_id string (required)
The user inputted reference ID
type string (required)
The type of Business Document being queried.
We currently support BUSINESS_REGISTRATION
image file (required)
The Business Document of mime type image/png, image/pdf, image/jpeg, image/jpg. Maximum file size 500MB
country string (required)
The country of Business Document being issued.
We currently support ID
document_name string (required)
The Document name of Business Document being queried.
We currently support SK_MENKEH

Business Document OCR Response

Example Business Document OCR Response - Pending

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-2ec00c2e-04a6-4836-871e-68185df17915",
    "created": "2022-02-25T06:56:20.808Z",
    "updated": "2022-02-25T06:56:20.808Z",
    "status": "PENDING",
    "result": {}
}

Example Business Document OCR Response - Completed
Business Document Example

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-32e6e523-6046-4db9-99ea-35a4f852ee86",
    "created": "2022-02-25T06:55:31.029Z",
    "updated": "2022-02-25T06:55:31.029Z",
    "status": "COMPLETED",
    "result": {
        "pages": 1,
        "data": [
            {
                "name": "director_names",
                "values": [
                    {
                        "value": "MATTHEW DAVID ROSA",
                        "confidence_level": 99.80309041341145
                    },
                    {
                        "value": "TIKA OSBOND SIRAIT",
                        "confidence_level": 99.58164469401042
                    },
                    {
                        "value": "SIVA SAJAN BHUPATHI RAJU",
                        "confidence_level": 99.03042030334473
                    }
                ]
            },
            {
                "name": "commisioner_names",
                "values": [
                    {
                        "value": "PANG SU KONG",
                        "confidence_level": 99.1666997273763
                    },
                    {
                        "value": "ANTHONY RICARD CATINELLA",
                        "confidence_level": 99.64801025390625
                    }
                ]
            },
            {
                "name": "shareholder_names",
                "values": [
                    {
                        "value": "METIS CONSULTANCY LIMITED",
                        "confidence_level": 99.80023193359375
                    },
                    {
                        "value": "WASPMOBILE SERVICES PRIVATE LIMITED",
                        "confidence_level": 99.5948486328125
                    }
                ]
            },
            {
                "name": "sk_menkeh_number",
                "values": {
                    "value": "AHU-0049135.AH.01.01.TAHUN 2016",
                    "confidence_level": 79.09121704101562
                }
            },
            {
                "name": "legal_entity_name",
                "values": {
                    "value": "PT DIGITAL VISION PUBLISHING",
                    "confidence_level": 98.27043151855469
                }
            },
            {
                "name": "date_of_registration",
                "values": {
                    "value": "07 Oktober 2016",
                    "confidence_level": 99.31755828857422
                }
            },
            {
                "name": "document_date",
                "values": {
                    "value": "03 November 2016",
                    "confidence_level": 99.49999237060547
                }
            },
            {
                "name": "akta_number",
                "values": {
                    "value": "02",
                    "confidence_level": 99.31755828857422
                }
            },
            {
                "name": "notary",
                "values": {
                    "value": "BAHDER DJOHAN RAZAK,SH",
                    "confidence_level": 97.16451263427734
                }
            },
            {
                "name": "place_of_registration",
                "values": {
                    "value": "KOTA ADMINISTRASI JAKARTA SELATAN",
                    "confidence_level": 99.05745697021484
                }
            }
        ]
    }
}

Example Business Document OCR Response - Completed with Unreadable Business Document Data

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-98dd66b2-79e8-47f4-ae5a-3e7073a90f52",
    "created": "2022-02-25T06:55:56.085Z",
    "updated": "2022-02-25T06:55:56.085Z",
    "status": "COMPLETED",
    "result": {
        "pages": 1,
        "data": [
            {
                "name": "director_names",
                "values": []
            },
            {
                "name": "commisioner_names",
                "values": []
            },
            {
                "name": "shareholder_names",
                "values": []
            },
            {
                "name": "sk_menkeh_number",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "akta_number",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "legal_entity_name",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "date_of_registration",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "notary",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "establishment_place",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            }
        ]
    }
}

Example Business Document OCR Response - FAILED

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-d49d6f9f-b419-4875-aa24-57888c2e9854",
    "created": "2022-02-25T06:56:09.479Z",
    "updated": "2022-02-25T06:56:09.479Z",
    "status": "FAILED",
    "failure_reason": "TEMPORARY_NETWORK_ERROR"
}

You will receive a JSON response with a reference id on submitting the POST request. Because it may take a few seconds to upload and process the image file, all results are returned to you in a callback. Be sure to have a callback URL configured for Business Document OCR in your account (Set it with type: BUSINESS_DOCUMENT_OCR_REQUEST). Please refer to Callback section for further details.

Endpoint: API Flow

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

Business Document OCR Schema

Parameter Description
id string (required)
A unique identifier of the Business Document image request for use in later API calls
reference_id string (optional)
An identifier of the Business Document image request that inputted by user
result json (required)
The text content we have extracted from the Business Document
status string (required)
The status of the OCR processing attempt
created string (required)
The receipt date of the OCR request. ISO8601 timestamp
updated string (required)
The last updated date of the OCR request. ISO8601 timestamp
type string (required)
The type of OCR request.
country string (required)
The country of Business Document being issued.
failure_reason string (optional)
The reason for the failure
document_name string (required)
The Document name of Business Document being queried

Result OCR Schema

Parameter Description
pages integer (required)
Extracted Business Document Pages
data array (required)
Extracted Business Document data

Business Document OCR Errors

Error Code Description
API_VALIDATION_ERROR
400		 The request payload does not match what was specified. Missing form fields are provided in the response payload.
FILE_TOO_LARGE
413		 The file is too large (> 500 MB. Please reduce file size before retrying.
UNSUPPORTED_CONTENT_TYPE
415		 The file is in an unsupported format.
Only PNG, JPG, PDF, JPEG are supported

Business Document OCR: Get by id

Endpoint: Get data request status

GET https://api.iluma.ai/v1/identity/document_ocr_requests/:id

Example Business Document OCR: Get by id Request

curl https://api.iluma.ai/v1/identity/document_ocr_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.

Business Document OCR: Get by id Request

Parameter Description
id string (required)
The ID of the request to retrieve. This ID must match the unique Business Document OCR request ID provided in our response at the time of resource creation

Endpoint: API Flow

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

Example Business Document OCR Response - Pending

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-2ec00c2e-04a6-4836-871e-68185df17915",
    "created": "2022-02-25T06:56:20.808Z",
    "updated": "2022-02-25T06:56:20.808Z",
    "status": "PENDING",
    "result": {}
}

Example Business Document OCR Response - Completed
Business Document Example

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-32e6e523-6046-4db9-99ea-35a4f852ee86",
    "created": "2022-02-25T06:55:31.029Z",
    "updated": "2022-02-25T06:55:31.029Z",
    "status": "COMPLETED",
    "result": {
        "pages": 1,
        "data": [
            {
                "name": "director_names",
                "values": [
                    {
                        "value": "MATTHEW DAVID ROSA",
                        "confidence_level": 99.80309041341145
                    },
                    {
                        "value": "TIKA OSBOND SIRAIT",
                        "confidence_level": 99.58164469401042
                    },
                    {
                        "value": "SIVA SAJAN BHUPATHI RAJU",
                        "confidence_level": 99.03042030334473
                    }
                ]
            },
            {
                "name": "commisioner_names",
                "values": [
                    {
                        "value": "PANG SU KONG",
                        "confidence_level": 99.1666997273763
                    },
                    {
                        "value": "ANTHONY RICARD CATINELLA",
                        "confidence_level": 99.64801025390625
                    }
                ]
            },
            {
                "name": "shareholder_names",
                "values": [
                    {
                        "value": "METIS CONSULTANCY LIMITED",
                        "confidence_level": 99.80023193359375
                    },
                    {
                        "value": "WASPMOBILE SERVICES PRIVATE LIMITED",
                        "confidence_level": 99.5948486328125
                    }
                ]
            },
            {
                "name": "sk_menkeh_number",
                "values": {
                    "value": "AHU-0049135.AH.01.01.TAHUN 2016",
                    "confidence_level": 79.09121704101562
                }
            },
            {
                "name": "legal_entity_name",
                "values": {
                    "value": "PT DIGITAL VISION PUBLISHING",
                    "confidence_level": 98.27043151855469
                }
            },
            {
                "name": "date_of_registration",
                "values": {
                    "value": "07 Oktober 2016",
                    "confidence_level": 99.31755828857422
                }
            },
            {
                "name": "document_date",
                "values": {
                    "value": "03 November 2016",
                    "confidence_level": 99.49999237060547
                }
            },
            {
                "name": "akta_number",
                "values": {
                    "value": "02",
                    "confidence_level": 99.31755828857422
                }
            },
            {
                "name": "notary",
                "values": {
                    "value": "BAHDER DJOHAN RAZAK,SH",
                    "confidence_level": 97.16451263427734
                }
            },
            {
                "name": "place_of_registration",
                "values": {
                    "value": "KOTA ADMINISTRASI JAKARTA SELATAN",
                    "confidence_level": 99.05745697021484
                }
            }
        ]
    }
}

Example Business Document OCR Response - Completed with Unreadable Business Document Data

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-98dd66b2-79e8-47f4-ae5a-3e7073a90f52",
    "created": "2022-02-25T06:55:56.085Z",
    "updated": "2022-02-25T06:55:56.085Z",
    "status": "COMPLETED",
    "result": {
        "pages": 1,
        "data": [
            {
                "name": "director_names",
                "values": []
            },
            {
                "name": "commisioner_names",
                "values": []
            },
            {
                "name": "shareholder_names",
                "values": []
            },
            {
                "name": "sk_menkeh_number",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "akta_number",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "legal_entity_name",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "date_of_registration",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "notary",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "establishment_place",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            }
        ]
    }
}

Example Business Document OCR Response - FAILED

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-d49d6f9f-b419-4875-aa24-57888c2e9854",
    "created": "2022-02-25T06:56:09.479Z",
    "updated": "2022-02-25T06:56:09.479Z",
    "status": "FAILED",
    "failure_reason": "TEMPORARY_NETWORK_ERROR"
}

Business Document OCR: Get by Reference id

Endpoint: Get data request status

GET https://api.iluma.ai/v1/identity/document_ocr_requests?reference_id=:reference_id&after_id=:after_id&limit=:limit

Example Business Document OCR: Get by id Request

curl --location --request GET 'https://api.iluma.ai/v1/identity/document_ocr_requests?reference_id=foo123&after_id=ocr-eeb78403-38c7-43d2-8de8-444a5fbaf653&limit=20'

You can inquire on the status of an existing request by making a GET request to the resource using the ID and Reference 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.

Business Document OCR: Get by Reference id Request

Parameter Description
id string (required)
The ID of the request to retrieve. This ID must match the unique Business Document OCR request ID provided in our response at the time of resource creation
reference_id string (required)
The reference_id of the request to retrieve. This reference_id is provided by the user
limit integer (required)
The limit is number of records retrieved from the database.

Endpoint: API Flow

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

Example Business Document OCR Response - Pending

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-2ec00c2e-04a6-4836-871e-68185df17915",
    "created": "2022-02-25T06:56:20.808Z",
    "updated": "2022-02-25T06:56:20.808Z",
    "status": "PENDING",
    "result": {}
}

Example Business Document OCR Response - Completed
Business Document Example

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-32e6e523-6046-4db9-99ea-35a4f852ee86",
    "created": "2022-02-25T06:55:31.029Z",
    "updated": "2022-02-25T06:55:31.029Z",
    "status": "COMPLETED",
    "result": {
        "pages": 1,
        "data": [
            {
                "name": "director_names",
                "values": [
                    {
                        "value": "MATTHEW DAVID ROSA",
                        "confidence_level": 99.80309041341145
                    },
                    {
                        "value": "TIKA OSBOND SIRAIT",
                        "confidence_level": 99.58164469401042
                    },
                    {
                        "value": "SIVA SAJAN BHUPATHI RAJU",
                        "confidence_level": 99.03042030334473
                    }
                ]
            },
            {
                "name": "commisioner_names",
                "values": [
                    {
                        "value": "PANG SU KONG",
                        "confidence_level": 99.1666997273763
                    },
                    {
                        "value": "ANTHONY RICARD CATINELLA",
                        "confidence_level": 99.64801025390625
                    }
                ]
            },
            {
                "name": "shareholder_names",
                "values": [
                    {
                        "value": "METIS CONSULTANCY LIMITED",
                        "confidence_level": 99.80023193359375
                    },
                    {
                        "value": "WASPMOBILE SERVICES PRIVATE LIMITED",
                        "confidence_level": 99.5948486328125
                    }
                ]
            },
            {
                "name": "sk_menkeh_number",
                "values": {
                    "value": "AHU-0049135.AH.01.01.TAHUN 2016",
                    "confidence_level": 79.09121704101562
                }
            },
            {
                "name": "legal_entity_name",
                "values": {
                    "value": "PT DIGITAL VISION PUBLISHING",
                    "confidence_level": 98.27043151855469
                }
            },
            {
                "name": "date_of_registration",
                "values": {
                    "value": "07 Oktober 2016",
                    "confidence_level": 99.31755828857422
                }
            },
            {
                "name": "document_date",
                "values": {
                    "value": "03 November 2016",
                    "confidence_level": 99.49999237060547
                }
            },
            {
                "name": "akta_number",
                "values": {
                    "value": "02",
                    "confidence_level": 99.31755828857422
                }
            },
            {
                "name": "notary",
                "values": {
                    "value": "BAHDER DJOHAN RAZAK,SH",
                    "confidence_level": 97.16451263427734
                }
            },
            {
                "name": "place_of_registration",
                "values": {
                    "value": "KOTA ADMINISTRASI JAKARTA SELATAN",
                    "confidence_level": 99.05745697021484
                }
            }
        ]
    }
}

Example Business Document OCR Response - Completed with Unreadable Business Document Data

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-98dd66b2-79e8-47f4-ae5a-3e7073a90f52",
    "created": "2022-02-25T06:55:56.085Z",
    "updated": "2022-02-25T06:55:56.085Z",
    "status": "COMPLETED",
    "result": {
        "pages": 1,
        "data": [
            {
                "name": "director_names",
                "values": []
            },
            {
                "name": "commisioner_names",
                "values": []
            },
            {
                "name": "shareholder_names",
                "values": []
            },
            {
                "name": "sk_menkeh_number",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "akta_number",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "legal_entity_name",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "date_of_registration",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "notary",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            },
            {
                "name": "establishment_place",
                "values": {
                    "value": null,
                    "confidence_level": 0
                }
            }
        ]
    }
}

Example Business Document OCR Response - FAILED

{
    "reference_id": "foo123",
    "type": "BUSINESS_REGISTRATION",
    "country": "ID",
    "document_name": "SK_MENKEH",
    "id": "ocr-d49d6f9f-b419-4875-aa24-57888c2e9854",
    "created": "2022-02-25T06:56:09.479Z",
    "updated": "2022-02-25T06:56:09.479Z",
    "status": "FAILED",
    "failure_reason": "TEMPORARY_NETWORK_ERROR"
}

Document OCR Capture

Endpoint: Retrieve capture link for Document OCR

POST https://api.iluma.ai/v1/identity/document_ocr_captures

Example Business Document OCR Request

curl https://api.iluma.ai/v1/identity/document_ocr_captures \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
       "types": ["IDENTITY_CARD", "BUSINESS_REGISTRATION"],
        "country": "PH",
        "reference_id": "1234",
    }'

This service allows you to request for a unique GUI link (one-time use) where your users can upload their KYC documents (Identity Card, Selfie, Business Registration Document). We will perform OCR extraction on the provided documents, liveness check on the Selfie, facial comparison between the Identity Card and the Selfie, and return all these results in a callback payload to you.


Supported country: 🇵🇭


The full workflow can be seen in this diagram, detailing out the point of interactions that you will need to integrate with, and further details on each endpoint is subsequently provided.

Document OCR Capture Request

Parameter Description
types array (required)
The type of document for OCR. Possible values IDENTITY_CARD, BUSINESS_REGISTRATION, SELFIE
country string (optional)
The country of document for OCR. Possible values PH (default if absent). Format ISO3166-2 country code
reference_id string (optional)
The client’s unique ID for this request

Document OCR Capture Response

Example Document OCR Capture Response - PENDING

{
    "reference_id": "foo123",
    "types": ["IDENTITY_CARD", "BUSINESS_REGISTRATION"],
    "country": "PH",
    "id": "ocr-98cdecb2-84b0-477b-b0e6-c5aa2bbdba4f",
    "created": "2022-04-06T07:33:32.106Z",
    "updated": "2022-04-06T07:33:32.106Z",
    "status": "PENDING",
    "capture_link": "www.iluma.ai"
}

Example Document OCR Capture Response - IN_PROGRESS

{
    "reference_id": "foo123",
    "types": ["IDENTITY_CARD", "BUSINESS_REGISTRATION"],
    "country": "PH",
    "id": "ocr-98cdecb2-84b0-477b-b0e6-c5aa2bbdba4f",
    "created": "2022-04-06T07:33:32.106Z",
    "updated": "2022-04-06T07:33:32.106Z",
    "status": "IN_PROGRESS",
    "capture_link": "www.iluma.ai"
}

Example Document OCR Capture Response - COMPLETED_REVIEW_REQUIRED 

{
    "reference_id": "foo123",
    "types": ["IDENTITY_CARD", "BUSINESS_REGISTRATION"],
    "country": "PH",
    "id": "ocr-98cdecb2-84b0-477b-b0e6-c5aa2bbdba4f",
    "created": "2022-04-06T07:33:32.106Z",
    "updated": "2022-04-06T07:33:32.106Z",
    "status": "COMPLETED_REVIEW_REQUIRED",
    "capture_link": "www.iluma.ai",
    "result": {
        "id_card_ocr": {
            "id": "fc8e83a9-cd47-4094-9ecd-37f1988233fd",
            "link": "a70daa99-f031-4d43-903e-81226c41761a.jpeg",
            "gender": "M",
            "address": "Street 17",
            "country": "PH",
            "surname": "Test",
            "given_name": "Test name",
            "is_tampered": false,
            "date_of_birth": "1985-02-03",
            "date_of_issue": "2018-06-20",
            "document_name": "Driver’s Licence",
            "date_of_expiry": "2027-06-19",
            "id_card_number": "P1111111A",
            "place_of_birth": "SASMUAN PAMPANGA"
        },
        "selfie": {
            "id": "e07193c3-8660-4ddf-91ed-addf86ea17f5",
            "link": "86b5d614-70bd-4e25-827f-da55eaa17963.jpeg",
            "are_eyes_open": true,
            "face_mask_detected": false,
            "is_face_cropped": false,
            "multiple_faces_detected": false,
            "is_live": true,
            "confidence": 99,
            "document_name": "Selfie"
        },
        "face_match_percentage": {
            "is_a_match": false,
            "match_score": 0.38
        },
        "business_registration_ocr": {
            "id": "8cd03b5b-5cf5-458e-a499-62543395e89d",
            "link": "571603d3-2b42-4cbe-a73a-ae36a49ec065.pdf",
            "address": "TANONG, MARIKINA CITY, NCR,SECOND DISTRICT,NATIONAL CAPITAL REGION (NCR)",
            "is_tampered": false,
            "business_name": "Testcompany LLC",
            "date_of_issue": "2018-05-03",
            "document_name": "Any Document",
            "date_of_expiry": "2028-05-03",
            "business_owner_name": "John Bold",
            "registration_number": "1111111",
            "date_of_registration": "2018-05-03"
        }
    }
}

Example Document OCR Capture Response - COMPLETED 

{
    "reference_id": "foo123",
    "types": ["IDENTITY_CARD", "BUSINESS_REGISTRATION"],
    "country": "PH",
    "id": "ocr-98cdecb2-84b0-477b-b0e6-c5aa2bbdba4f",
    "created": "2022-04-06T07:33:32.106Z",
    "updated": "2022-04-06T07:33:32.106Z",
    "status": "COMPLETED",
    "capture_link": "www.iluma.ai",
    "result": {
        "id_card_ocr": {
            "id": "fc8e83a9-cd47-4094-9ecd-37f1988233fd",
            "link": "a70daa99-f031-4d43-903e-81226c41761a.jpeg",
            "gender": "M",
            "address": "Street 17",
            "country": "PH",
            "surname": "Test",
            "given_name": "Test name",
            "is_tampered": false,
            "date_of_birth": "1985-02-03",
            "date_of_issue": "2018-06-20",
            "document_name": "Driver’s Licence",
            "date_of_expiry": "2027-06-19",
            "id_card_number": "P1111111A",
            "place_of_birth": "SASMUAN PAMPANGA"
        },
        "selfie": {
            "id": "e07193c3-8660-4ddf-91ed-addf86ea17f5",
            "link": "86b5d614-70bd-4e25-827f-da55eaa17963.jpeg",
            "are_eyes_open": true,
            "face_mask_detected": false,
            "is_face_cropped": false,
            "multiple_faces_detected": false,
            "is_live": true,
            "confidence": 99,
            "document_name": "Selfie"
        },
        "face_match_percentage": {
            "is_a_match": false,
            "match_score": 0.38
        },
        "business_registration_ocr": {
            "id": "8cd03b5b-5cf5-458e-a499-62543395e89d",
            "link": "571603d3-2b42-4cbe-a73a-ae36a49ec065.pdf",
            "address": "TANONG, MARIKINA CITY, NCR,SECOND DISTRICT,NATIONAL CAPITAL REGION (NCR)",
            "is_tampered": false,
            "business_name": "Testcompany LLC",
            "date_of_issue": "2018-05-03",
            "document_name": "Any Document",
            "date_of_expiry": "2028-05-03",
            "business_owner_name": "John Bold",
            "registration_number": "1111111",
            "date_of_registration": "2018-05-03"
        }
    }
}

Example Document OCR Capture Response - FAILED

{
    "reference_id": "foo123",
    "types": ["IDENTITY_CARD", "BUSINESS_REGISTRATION"],
    "country": "PH",
    "id": "ocr-d49d6f9f-b419-4875-aa24-57888c2e9854",
    "created": "2022-02-25T06:56:09.479Z",
    "updated": "2022-02-25T06:56:09.479Z",
    "status": "FAILED",
    "failure_reason": "TEMPORARY_NETWORK_ERROR"
}

You will receive a JSON response with a reference id on submitting the POST request. Because it may take a few seconds to upload and process the image file, all result are returned to you in a callback. Be sure to have a callback URL configured for Document OCR Capture in your account (Set it with type: DOCUMENT_OCR_CAPTURE_REQUEST). Please refer to Callback section for further details.

Document OCR Capture Schema

Parameter Description
id string (required)
A unique identifier of the document request for use in later API calls
reference_id string (optional)
The client’s unique ID for this request
result json (optional)
Present if status is COMPLETED or COMPLETED_REVIEW_REQUIRED. Object of either id_card_ocr object, selfie object, face_match_percentage object or business_registration_ocr objects e.g.,
status string (required)
Capture process. Possible values: IN_PROGRESS - capture flow has finished and ocr has not completed, COMPLETED - flow has finished and ocr is completed, COMPLETED_REVIEW_REQUIRED - flow has finished, but additional review is needed,FAILED - flow interrupted and/or fail at any stage,
created string (required)
The receipt date of the OCR request. ISO8601 timestamp
updated string (required)
The last updated date of the OCR request. ISO8601 timestamp
types array (required)
The type of document for OCR. Possible values IDENTITY_CARD, BUSINESS_REGISTRATION, SELFIE
country string (required)
The country of document for OCR. Possible values PH
failure_reason string (optional)
The reason for the failure
capture_link string (required)
URL to the capture UI

id_card_ocr Schema

Parameter Description
id string (required)
A unique identifier for each document uploaded
document_name string (required)
Passport, Driver’s Licence, UMID, PhilSys, etc
link string (required)
link to the document captured
id_card_number string (required)
The identity card number extracted
given_name string (required)
Name of card holder (full_name if not able to split)
surname string (optional)
Surname
date_of_birth string (required)
Date of Birth. Format YYYY-MM-DD
gender string (required)
Gender. Possible values: M for Male, F for Female
date_of_expiry string (optional)
Date of Expiry
address string (optional)
Address as shown on the identity card.
country string (required)
The issuing country of the document. ISO3166-2 country code.
date_of_issue string (required)
Date of Issue
place_of_birth string (required)
Place of Birth
is_tampered boolean (required)
Whether doc have been tampered with

Selfie object

Payload if types include IDENTITY_CARD

Parameter Description
id string (required)
A unique identifier for each document uploaded
document_name string (required)
Selfie
link string (required)
link to the document captured
are_eyes_open boolean (required)
This parameter will detect if the eyes of the person clicking the selfie are open.
is_face_cropped boolean (required)
Whether face cropped in the image.
face_mask_detected boolean (required)
Whether a face mask was detected in the image.
multiple_faces_detected boolean (required)
Whether multiple prominent faces were found in the selfie.
is_live boolean (required)
Liveness check result
confidence string (required)
Confidence score on is_live flag

Face match percentage object

Payload if types include IDENTITY_CARD & SELFIE

Parameter Description
is_a_match boolean (required)
Whether the selfie is match with face in given identity document
match_score number (required)
Score of match percentage

business_registration_ocr Schema

Parameter Description
id string (required)
A unique identifier for each document uploaded
document_name string (required)
DTI, GIS, any other doc type
trn_number string (optional)
TRN number if document_name is DTI
link string (required)
link to the document captured
registration_number string (required)
The business registration number extracted
business_name string (required)
Name of card holder (full_name if not able to split)
date_of_registration string (required)
Date of registration. Format YYYY-MM-DD
date_of_expiry string (optional)
Date of Expiry
address string (optional)
Address as shown on the document.
country string (required)
The issuing country of the document. ISO3166-2 country code.
date_of_issue string (required)
Date of Issue
business_owner_name string (required)
name of business owner
is_tampered boolean (required)
Whether doc have been tampered with

Document OCR Capture Errors

Error Code Description
API_VALIDATION_ERROR
400		 The request payload does not match what was specified. Missing form fields are provided in the response payload.
SERVER_ERROR
500		 The service is down or other errors

Document OCR Capture: Get by id

Endpoint: Get data request status

GET https://api.iluma.ai/v1/identity/document_ocr_captures/:id

Example Document OCR Capture: Get by id Request

curl https://api.iluma.ai/v1/identity/document_ocr_captures/ocr-98cdecb2-84b0-477b-b0e6-c5aa2bbdba4f
    -X GET \
    -u iluma_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:

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.

Document OCR Capture: Get by id Request

Parameter Description
id string (required)
The unique request ID being retrieved

Example Document OCR Capture Response 

{
    "reference_id": "foo123",
    "types": ["IDENTITY_CARD", "BUSINESS_REGISTRATION"],
    "country": "PH",
    "id": "ocr-98cdecb2-84b0-477b-b0e6-c5aa2bbdba4f",
    "created": "2022-04-06T07:33:32.106Z",
    "updated": "2022-04-06T07:33:32.106Z",
    "status": "COMPLETED",
    "capture_link": "www.iluma.ai",
    "result": {
        "id_card_ocr": {
            "id": "fc8e83a9-cd47-4094-9ecd-37f1988233fd",
            "link": "a70daa99-f031-4d43-903e-81226c41761a.jpeg",
            "gender": "M",
            "address": "Street 17",
            "country": "PH",
            "surname": "Test",
            "given_name": "Test name",
            "is_tampered": false,
            "date_of_birth": "1985-02-03",
            "date_of_issue": "2018-06-20",
            "document_name": "Driver’s Licence",
            "date_of_expiry": "2027-06-19",
            "id_card_number": "P1111111A",
            "place_of_birth": "SASMUAN PAMPANGA"
        },
        "selfie": {
            "id": "e07193c3-8660-4ddf-91ed-addf86ea17f5",
            "link": "86b5d614-70bd-4e25-827f-da55eaa17963.jpeg",
            "are_eyes_open": true,
            "face_mask_detected": false,
            "is_face_cropped": false,
            "multiple_faces_detected": false,
            "is_live": true,
            "confidence": 99,
            "document_name": "Selfie"
        },
        "face_match_percentage": {
            "is_a_match": false,
            "match_score": 0.38
        },
        "business_registration_ocr": {
            "id": "8cd03b5b-5cf5-458e-a499-62543395e89d",
            "link": "571603d3-2b42-4cbe-a73a-ae36a49ec065.pdf",
            "address": "TANONG, MARIKINA CITY, NCR,SECOND DISTRICT,NATIONAL CAPITAL REGION (NCR)",
            "is_tampered": false,
            "business_name": "Testcompany LLC",
            "date_of_issue": "2018-05-03",
            "document_name": "Any Document",
            "date_of_expiry": "2028-05-03",
            "business_owner_name": "John Bold",
            "registration_number": "1111111",
            "date_of_registration": "2018-05-03"
        }
    }
}

Document OCR Capture: Get by id - Errors

Error Code Description
DATA_NOT_FOUND
404		 The request id requested does not exist
SERVER_ERROR
500		 The service is down or other errors

Document OCR Capture: Get by Reference id

Endpoint: Get data request status

GET https://api.iluma.ai/v1/identity/document_ocr_capture?reference_id=:reference_id&after_id=:after_id&limit=:limit

Example Document OCR Capture: Get by id Request

curl --location --request GET 'https://api.iluma.ai/v1/identity/document_ocr_capture?reference_id=1234&after_id=ocr-eeb78403-38c7-43d2-8de8-444a5fbaf653&limit=20'

You can inquire on the status of an existing request by making a GET request to the resource using the ID and Reference 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.

Document OCR Capture: Get by Reference id Request

Parameter Description
reference_id string (required)
The reference_id of the request to retrieve. This reference_id is provided by the user
limit integer (optional)
The limit is number of records retrieved from the database. Defaults to 10
after_id string (optional)
The cursor for the start of the page

Example Document OCR Capture Response

{
    "data": [
        {
            "reference_id": "1234",
            "types": ["IDENTITY_CARD", "BUSINESS_REGISTRATION"],
            "country": "PH",
            "id": "ocr-98cdecb2-84b0-477b-b0e6-c5aa2bbdba4f",
            "created": "2022-04-06T07:33:32.106Z",
            "updated": "2022-04-06T07:33:32.106Z",
            "status": "COMPLETED",
            "capture_link": "www.iluma.ai",
            "result": {
                "id_card_ocr": {
                    "id": "fc8e83a9-cd47-4094-9ecd-37f1988233fd",
                    "link": "a70daa99-f031-4d43-903e-81226c41761a.jpeg",
                    "gender": "M",
                    "address": "Street 17",
                    "country": "PH",
                    "surname": "Test",
                    "given_name": "Test name",
                    "is_tampered": false,
                    "date_of_birth": "1985-02-03",
                    "date_of_issue": "2018-06-20",
                    "document_name": "Driver’s Licence",
                    "date_of_expiry": "2027-06-19",
                    "id_card_number": "P1111111A",
                    "place_of_birth": "SASMUAN PAMPANGA"
                },
                "selfie": {
                    "id": "e07193c3-8660-4ddf-91ed-addf86ea17f5",
                    "link": "86b5d614-70bd-4e25-827f-da55eaa17963.jpeg",
                    "are_eyes_open": true,
                    "face_mask_detected": false,
                    "is_face_cropped": false,
                    "multiple_faces_detected": false,
                    "is_live": true,
                    "confidence": 99,
                    "document_name": "Selfie"
                },
                "face_match_percentage": {
                    "is_a_match": false,
                    "match_score": 0.38
                },
                "business_registration_ocr": {
                    "id": "8cd03b5b-5cf5-458e-a499-62543395e89d",
                    "link": "571603d3-2b42-4cbe-a73a-ae36a49ec065.pdf",
                    "address": "TANONG, MARIKINA CITY, NCR,SECOND DISTRICT,NATIONAL CAPITAL REGION (NCR)",
                    "is_tampered": false,
                    "business_name": "Testcompany LLC",
                    "date_of_issue": "2018-05-03",
                    "document_name": "Any Document",
                    "date_of_expiry": "2028-05-03",
                    "business_owner_name": "John Bold",
                    "registration_number": "1111111",
                    "date_of_registration": "2018-05-03"
                }
            }
        },
        {
            "id": "ocr-ecef7986-b9d6-4e50-8168-8b3d0b110262",
            "capture_link": "www.iluma.ai",
            "reference_id": "1234",
            "country": "PH",
            "types": [
                "IDENTITY_CARD"
            ],
            "status": "PENDING",
            "created": "2022-04-05T12:14:23.908Z",
            "updated": "2022-04-05T12:14:23.908Z"
        },
        {
            "id": "ocr-22bad02a-bbe9-4844-8959-6c50da197e60",
            "capture_link": "www.iluma.ai",
            "reference_id": "1234",
            "country": "PH",
            "types": [
                "IDENTITY_CARD"
            ],
            "status": "PENDING",
            "created": "2022-04-05T12:17:05.638Z",
            "updated": "2022-04-05T12:17:05.638Z"
        }
    ],
    "has_more": false,
    "links": [
        {
            "href": "/v1/document_ocr_captures?reference_id=1234",
            "rel": "first",
            "method": "GET"
        },
        {
            "href": "/v1/document_ocr_captures?reference_id=1234",
            "rel": "self",
            "method": "GET"
        }
    ]
}

Document OCR Capture: Recapture Flow by id

Endpoint: Recapture Flow by id

GET https://api.iluma.ai/v1/identity/document_ocr_captures/:id/recapture

Example Document OCR Capture: Recapture Flow by id

curl https://api.iluma.ai/v1/identity/document_ocr_captures/ocr-98cdecb2-84b0-477b-b0e6-c5aa2bbdba4f/recapture
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
       "types": ["IDENTITY_CARD"]
    }'

This endpoint will let you request a recapture on a Business document

Document OCR Recapture:

Path parameters Description
id string (required)
The unique request ID being retrieved
Body Description
types array (required)
The type of document for OCR. Possible values IDENTITY_CARD, BUSINESS_REGISTRATION, SELFIE

Example Document OCR Capture Response 

{
    "reference_id": "foo123",
    "types": ["IDENTITY_CARD"],
    "country": "PH",
    "id": "ocr-98cdecb2-84b0-477b-b0e6-c5aa2bbdba4f",
    "created": "2022-04-06T07:33:32.106Z",
    "updated": "2022-04-06T07:33:32.106Z",
    "status": "RECAPTURE_PENDING",
    "capture_link": "www.iluma.ai"
}

Document OCR Recapture Errors

Error Code Description
DATA_NOT_FOUND
404		 The request id requested does not exist
API_VALIDATION_ERROR
400		 The request payload does not match what was specified. Missing form fields are provided in the response payload.
SERVER_ERROR
500		 The service is down or other errors
Parameter Description
id string (required)
The unique request ID being retrieved
link string (required)
Link to the captured document

Endpoint: Download captured document using link

GET https://api.iluma.ai/v1/identity/captures/:id/results/:link/download
Error Code Description
DATA_NOT_FOUND
404		 The request id requested does not exist
API_VALIDATION_ERROR
400		 The request payload does not match what was specified. Missing form fields are provided in the response payload.
SERVER_ERROR
500		 The service is down or other errors

Business Document Verification 🇵🇭

Endpoint: Perform Business Document Verification

POST https://api.iluma.ai/v0/identity/business_document_verifications

Example Business Document Verification Request

curl https://api.iluma.ai/v0/identity/business_document_verifications \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
          "document_id": "ABC Shop",
          "document_id_type": "Business Name",
          "type": "DTI",
          "country": "PH",
          "reference_id": "test",
          "match_parameters": {
            "certificate_number": "1234567",
            "owner_name": "John Doe",
            "registration_date": "2022-01-01",
            "business_legal_name": "Shop ABC"
          }
        }'

The Business Document Verification endpoint allows validation of a DTI business registration document against official government databases. Please note that this endpoint only applies to Filipino businesses.

Endpoint: API Flow

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

Business Document Verification Request

Parameter Description
document_id string (required)
Unique identifier of document provided
match_parameters object (required) MatchParameters
Parameters to be matched against the official database
document_id_type string
Type of document id provided.
Enum: Business Name(Default), Reference Code, TRN, PBN
type string
Type of document being validated country.
Enum: DTI(Default)
country string
The issuing country of the document.
Enum: PH(Default)
reference_id string
Customer identifier for this request

Match Parameters

Parameter Description
certificate_number string
Certificate number per DTI certificate / BNN
business_legal_name string
Business legal name per DTI certificate (if this is not used as document identifier)
owner_name string
Name of the business owner per DTI certificate.
registration_date string (date YYYY-MM-DD)
Registration date / date the DTI certificate is valid from.

Business Document Verification Response

Because it may take a few seconds to validate the business registration document against official government databases, all results are returned to you in a callback. Be sure to have a callback URL configured in your account (Set it with type: DTI_VALIDATION). Please refer to Callback section for further details.

Example Business Document Verification Response

{
  "document_id": "ABC Shop",
  "document_id_type": "Business Name",
  "type": "DTI",
  "country": "PH",
  "reference_id": "test",
  "match_parameters": {
    "certificate_number": "1234567",
    "owner_name": "John Doe",
    "registration_date": "2022-01-01",
    "business_legal_name": "Shop ABC"
  },
  "id": "bdvr-a02c4549-69f6-4319-94fb-4c90c0d14082",
  "created": "2022-07-26T07:13:04.972Z",
  "updated": "2022-07-26T07:13:04.972Z",
  "status": "PENDING"
}

Document Verification Response

Parameter Description
id string (required)(bdvr-)
A unique identifier of the request for use in later API calls
created string (required)(date-time ISO8601)
The receipt date of the request. ISO8601 timestamp in UTC
updated string (required)(date-time ISO8601)
The last updated date of the request. ISO8601 timestamp in UTC
status string (required)
The status of the request.
Enum: PENDING, COMPLETED, FAILED
document_id string (required)
Unique identifier of document provided
document_id_type string (required)
Type of document id provided
type string (required)
Type of document being validated
country string (required)
The issuing country of the document
reference_id string
Customer identifier for this request
match_parameters object (required) MatchParameters
Parameters to be matched against the official database
is_found boolean
Present if status='COMPLETED', whether the document was found in official database
result object MatchParametersResult
The validation result, present if status='COMPLETED' and is_found=true

Match Parameters Result

Parameter Description
is_certificate_number_match boolean
Whether the certificate number was an exact match
is_registration_date_match boolean
Whether the registration date was an exact match
business_legal_name_score number
Whether the business legal name was a fuzzy match with the record for this DTI certificate
owner_name_score number
Whether the owner's name was a fuzzy match with the record for this DTI certificate

Business Document Verification Request Errors

Error Code Description
API_VALIDATION_ERROR
400		 The request payload does not match what was specified. Missing form fields are provided in the response payload.
REQUEST_FORBIDDEN_ERROR
403		 The API key lacks permissions for this endpoint

Business Document Verification : Get by id

Endpoint: Get Business Document Verification by request id

GET https://api.iluma.ai/v0/identity/business_document_verifications/:id

Example Business Document Verification: Get by request id

curl https://api.iluma.ai/v0/identity/business_document_verifications/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 DocumentVerificationResponse.

Endpoint: API Flow

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

Business Document Verification: Get by request id

Parameter Description
id string
The unique request ID being retrieved

Get Business Document Verification Response

Pending

{
  "document_id": "ABC Shop",
  "document_id_type": "Business Name",
  "type": "DTI",
  "country": "PH",
  "reference_id": "test",
  "match_parameters": {
    "certificate_number": "1234567",
    "owner_name": "John Doe",
    "registration_date": "2022-01-01",
    "business_legal_name": "Shop ABC"
  },
  "id": "bdvr-a02c4549-69f6-4319-94fb-4c90c0d14082",
  "created": "2022-07-26T07:13:04.972Z",
  "updated": "2022-07-26T07:13:04.972Z",
  "status": "PENDING"
}

Completed (Found)

{
  "document_id": "ABC Shop",
  "document_id_type": "Business Name",
  "type": "DTI",
  "country": "PH",
  "reference_id": "test",
  "match_parameters": {
    "certificate_number": "1234567",
    "owner_name": "John Doe",
    "registration_date": "2022-01-01",
    "business_legal_name": "Shop ABC"
  },
  "id": "bdvr-5a822398-904b-4bac-aae7-5275fa732d45",
  "created": "2022-07-26T07:12:54.932Z",
  "updated": "2022-07-26T07:12:54.932Z",
  "status": "COMPLETED",
  "is_found": true,
  "result": {
    "is_certificate_number_match": true,
    "is_registration_date_match": true,
    "owner_name_score": 100,
    "business_legal_name_score": 78
  }
}

Completed (Not Found)

{
  "document_id": "ABC Shop",
  "document_id_type": "Business Name",
  "type": "DTI",
  "country": "PH",
  "reference_id": "test",
  "match_parameters": {
    "certificate_number": "1234567",
    "owner_name": "John Doe",
    "registration_date": "2022-01-01",
    "business_legal_name": "Shop ABC"
  },
  "id": "bdvr-54959185-9d32-43d3-9ef6-58ce7ea89487",
  "created": "2022-07-26T07:12:43.603Z",
  "updated": "2022-07-26T07:12:43.603Z",
  "status": "COMPLETED",
  "is_found": false
}

Failed

{
  "document_id": "ABC Shop",
  "document_id_type": "Business Name",
  "type": "DTI",
  "country": "PH",
  "reference_id": "test",
  "match_parameters": {
    "certificate_number": "1234567",
    "owner_name": "John Doe",
    "registration_date": "2022-01-01",
    "business_legal_name": "Shop ABC"
  },
  "id": "bdvr-231cc051-7ced-453c-9349-7b3489c8e04f",
  "created": "2022-07-26T07:12:01.190Z",
  "updated": "2022-07-26T07:12:01.190Z",
  "status": "FAILED",
  "failure_reason": "TEMPORARY_NETWORK_ERROR"
}

Get Business Document Verification by ID Errors

Error Code Description
API_VALIDATION_ERROR
400		 The request payload does not match what was specified. Missing form fields are provided in the response payload.
DATA_NOT_FOUND
404		 The request id requested does not exist
REQUEST_FORBIDDEN_ERROR
403		 The API key lacks permissions for this endpoint

Business Document Verification : Get by reference id

Endpoint: Get Business Document Verification by reference id

GET https://api.iluma.ai/v0/identity/business_document_verifications?reference_id=:reference_id&after_id=:after_id&limit=:limit

Example Business Document Verification: Get by reference id

curl https://api.iluma.ai/v0/identity/business_document_verifications?reference_id=foo123&after_id=bdvr-eeb78403-38c7-43d2-8de8-444a5fbaf653&limit=20\
    -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 reference id given when creating the request resource. You will receive an array of DocumentVerificationResponse.

Business Document Verification: Get by reference id

Parameter Description
reference_id string
The client’s reference ID being retrieved
limit number
The number of results to return in a page. Defaults to 10
after_id string
The cursor for the start of the page. This refers to the request_id of the last request returned in previous page

Endpoint: API Flow

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

Get Business Document Verification by Reference ID Response

{
  "data": [
    {
      "document_id": "ABC Shop",
      "document_id_type": "Business Name",
      "type": "DTI",
      "country": "PH",
      "reference_id": "test",
      "match_parameters": {
        "certificate_number": "1234567",
        "owner_name": "John Doe",
        "registration_date": "2022-01-01",
        "business_legal_name": "Shop ABC"
      },
      "id": "bdvr-5a822398-904b-4bac-aae7-5275fa732d45",
      "created": "2022-07-26T07:12:54.932Z",
      "updated": "2022-07-26T07:12:54.932Z",
      "status": "COMPLETED",
      "is_found": true,
      "result": {
        "is_certificate_number_match": true,
        "is_registration_date_match": true,
        "owner_name_score": 100,
        "business_legal_name_score": 78
      }
    }
  ],
  "has_more": true,
  "links": [
    {
      "href": "/v0/identity/business_document_verifications/",
      "rel": "first",
      "method": "GET"
    },
    {
      "href": "/v0/identity/business_document_verifications/?limit=10",
      "rel": "self",
      "method": "GET"
    },
    {
      "rel": "next",
      "href": "/v0/identity/business_document_verifications/?limit=10&after_id=653941f5-95d9-42d6-a40c-51c21e85b8d6",
      "method": "GET"
    }
  ]
}

Get Business Document Verification by Reference ID Response

Parameter Description
data array of DocumentVerificationResponse
An array of previously created requests found by reference_id provided. Will return an empty array if no resources are found.
links array of LinkSchema
HATEOAS implementation on after_id
has_more boolean
True if there are additional pages in the result

Parameter Description
href string
Target URI that should contain a target to Internationalized Resource Identifiers (IRI)
rel string
The link relation type described how the current context (source) is related to target
method string
HTTP method attributes for target IRI

Get Business Document Verification by Reference ID Errors

Error Code Description
API_VALIDATION_ERROR
400		 The request payload does not match what was specified. Missing form fields are provided in the response payload.
REQUEST_FORBIDDEN_ERROR
403		 The API key lacks permissions for this endpoint

Anti-Money Laundering

Iluma's AML product (Anti Money-Laundering) help you to check the risk of an individual when they interact with you. We help you verify whether individuals or entities are listed in international sanctions lists or politically-exposed persons (PEPs). Contact us if you are interested in seeing something specific.

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:

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:

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

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

API Flow

These are the flow of our API across all our of our endpoints. If you have any questions please contact us.

Synchronous Request

Asynchronous Request

Get Request

Errors

Below are some of most common errors across all our endpoints. Specific errors are located under each endpoint. If you have any questions please contact us.

Error code Meaning
400 Bad request, e.g. validation error, malformed payload
401 Unauthorised access, e.g. the API key is invalid
403 Forbidden access, e.g. API key does not have permission for this endpoint
404 Page or endpoint not found
413 The file is too large. Please refer to the api docs on the particular section for your endpoint to see the corresponding restrictions.
415 The file is in an unsupported format. Please refer to the api docs on the particular section for your endpoint to see the corresponding restrictions.
429 API rate limit exceeded. You should wait for a short while and try the requests again for this endpoint until you no longer receive this error state.
500 Unhandled error - contact us when this happens.
503 Service Unavailable - All upstream data suppliers are unavailable
bash