Introduction

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

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

Learn our APIs with Postman

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

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

Onboarding

Flow Diagram

Integration guide

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

1. Getting set up

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

This section will guide you through three steps

• Getting sample code
• Authenticating your requests
• Setting callbacks

Getting sample code

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

Example code snippet to copy

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

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

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

Authenticating your requests

Example: Using the development API Key in this API documentation

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw

Option 1: Use the functionality built into your request library

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

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

Option 2: Manually construct the Authorization header for basic auth

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

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw:

Next, Base64 encode the colon appended key to get

aWx1bWFfZGV2ZWxvcG1lbnRfRlg0ZjBNNXN4RGdrNXFGeVpuazYwWmVuZ0FmQTlvMzF4M2VjZDI5dmloamM0Vmh5SjhGY2xaaEhqanc6

Then construct your API requests with the Authorization header

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

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

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

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

• Have an API key
• Have a callback server
• Have set up callbacks

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

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

• There is no cost for making requests in development mode
• Changing your input payload may not achieve a different response payload
• You cannot rely on the verification results in this environment

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

3. Simulating responses

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

Note that:

• Requests made to validation endpoints (e.g., ewallet name validation) will mirror your request payload
• Requests made to data extraction endpoints (e.g., ID card OCR) will return dummy data
• Format validation will be applied before assessing the magic reply header, so you will receive API_VALIDATION_ERROR if you provide a request payload which doesn't comply to the API specification
• These headers are available in BOTH development and live environments
• Requests made with these headers will NOT be charged in the live environment

Using "Magic Reply" headers.

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

• Pending: Your request has been submitted but the response has not yet been received from the data source. No callback will be sent for this state.
• Completed: Your request has completed processing
  • Data found: Data has been found or extracted. A callback will be sent
  • Data not found: Data has not been found or was unable to be extracted. A callback will be sent
• Failed: Your request encountered an error during processing

More details.

Authentication

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

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw

First, add a colon at the end

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw:

Finally, Base64 encode the colon appended key to get

aWx1bWFfZGV2ZWxvcG1lbnRfRlg0ZjBNNXN4RGdrNXFGeVpuazYwWmVuZ0FmQTlvMzF4M2VjZDI5dmloamM0Vmh5SjhGY2xaaEhqanc6

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

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

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

Get API Key

Endpoint: Get API Key

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

Example Get API Key Request

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

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

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

Identity

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

Bank Name Validator V1

Endpoint: Validate name on bank account

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

Example Bank Name Validator Request

curl https://api.iluma.ai/v1/identity/bank_account_data_requests \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
    "bank_account_number": "1234567890",
    "bank_code": "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. It also provides an indication whether the account is a normal bank account or not (e.g a Virtual Account), allowing you to confirm that the account is truly owned by the individual and minimising your exposure to fraud.

Bank Name Validator Request

Parameter	Description
bank_account_number	string (required) The bank account number
bank_code	string (required) The bank code. See Bank Codes
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": "BCA",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "59e608887eb26d005d44aeb8",
    "reference_id": "foo123"
}

Example Bank Name Validator Response (Account found)

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

Example Bank Name Validator Response (Account not found)

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

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

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

Bank Name Validator Schema

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

Bank Name Validator Errors

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

Endpoint: API Flow

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

Bank Name Validator: Get by id

Endpoint: Get data request status

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

Example Bank Name Validator: Get by id Request

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

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

Bank Name Validator: Get by id Request

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

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

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

Example Bank Name Validator Response (Account found)

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

Example Bank Name Validator Response (Account not found)

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

Endpoint: API Flow

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

Bank Name Validator V1.1

Endpoint: Validate name on bank account

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

Example Bank Name Validator Request

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

The Bank Name Validator can be used to look up the name of an account holder for bank accounts in Indonesia. 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. See Bank Codes
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": "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": "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": "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": "BCA",
    "created": "2017-07-03T10:51:44.484Z",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_5c6ba591cf3c3867d75053d7",
    "reference_id": "foo123",
    "result": {
        "is_found": false
    },
}

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

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

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

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

Bank Name Validator Schema

Parameter	Description
bank_code	string (required) The bank code. See Bank Codes
bank_account_number	string (required) The bank account number
status	string (required) PENDING The name validation request is still being processed 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, 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/v1.1/identity/bank_account_data_requests/:id

Example Bank Name Validator: Get by id Request

curl https://api.iluma.ai/v1.1/identity/bank_account_data_requests/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": "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": "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": "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": "BCA",
    "created": "2017-07-03T10:51:44.484Z",
    "updated": "2017-07-03T10:51:44.484Z",
    "id": "bknv_5c6ba591cf3c3867d75053d7",
    "reference_id": "foo123",
    "result": {
        "is_found": false
    },
}

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

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

Bank Name Validator Schema

Please refer to this section.

Endpoint: API Flow

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

KTP Name validator

Endpoint: Validate KTP details

POST https://api.iluma.ai/v1/identity/ktp_name/validations

Example KTP Validator Request

curl https://api.iluma.ai/v1/identity/ktp_name/validations \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
        "nik": "1234567890123456",
        "name": "FIRA DIYANKA"
    }'

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

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

KTP Validator Request

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

Example KTP Validator Response

{
    "nik": "1234567890123456",
    "status": "FOUND",
    "name_match": "true"
}

KTP Validator Response

Parameter	Description
nik	string (required) The ID card identification number.
status	string (required) An enum indicating whether the NIK in question was found in our sources. Possible values are FOUND and NOT_FOUND.
name_match	boolean (required) A true/false indicating whether the name was a match or not.

KTP Validator Errors

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

Endpoint: API Flow

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

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 individual's face and ID card are clearly visible and not blurred.
• The background size is not larger than the ID card object.
• Selfie taken together with the ID card is not recommended. For accurate results, they should be provided separately.

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.

CFT

Endpoint: Query for potential matches on official cft databases

POST https://api.iluma.ai/v1/identity/cft/individual_watchlist

Example CFT Individual Watchlist

curl https://api.iluma.ai/v1/identity/cft/individual_watchlist \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
        "given_name": "Abdul",
        "surname": "Aziz"
    }'

The CFT (Combating the Financing of Terrorism) endpoint can be used to check if an individual is connected with terrorism or proliferating weapons of mass destruction based on a range of Indonesian government databases

CFT Request

Parameter	Description
given_name	string (required) The given name that will be used for name matching purposes
surname	string (optional) The surname that will be used for name matching purposes

Example Individual CFT Watchlist Response

{
    "request_name": "Abdul Aziz",
    "results": [
        {
            "pid": "dttot_77",
            "name": "AIMAN MUHAMMED RABI AL-ZAWAHIRI",
            "aliases": [
                "AYMAN AL-ZAWAHARI",
                "AHMED FUAD SALIM",
                "AL ZAWAHRY AIMAN  MOHAMED RABI ABDEL MUAZ",
                "AL ZAWAHIRI AYMAN",
                "ABDUL QADER ABDUL AZIZ ABDUL MOEZ AL DOCTOR",
                "AL ZAWAHRY AIMAN MOHAMED RABI",
                "AL ZAWAHRY AIMAN MOHAMED RABIE",
                "AL ZAWAHRY AIMAN MOHAMED ROBI",
                "DHAWAHRI AYMAN",
                "EDDAOUAHIRI AYMAN",
                "NUR AL DEEN ABU MOHAMMED",
                "AYMAN AL ZAWAHARI",
                "AHMAD FUAD SALIM"
            ],
            "place_of_birth": "Giza, Mesir",
            "date_of_birth": "19-Jun-51",
            "nationality": "Mesir",
            "origin": "DTTOT",
            "country_code": "EG"
        },
        {
            "pid": "dttot_138",
            "name": "DAWOOD IBRAHIM KASKAR",
            "aliases": [
                "DAWOOD EBRAHIM",
                "SHEIKH DAWOOD HASSAN",
                "ABDUL HAMID ABDUL AZIZ",
                "ANIS IBRAHIM",
                "AZIZ DILIP",
                "DAUD HASAN SHAIKH IBRAHIM KASKAR",
                "DAUD IBRAHIM MEMON KASKAR",
                "DAWOOD HASAN IBRAHIM KASKAR",
                "DAWOOD IBRAHIM MEMON",
                "DAWOOD SABRI",
                "KASKAR DAWOOD HASAN",
                "SHAIKH MOHD ISMAIL ABDUL REHMAN",
                "DOWOOD HASSAN SHAIKH IBRAHIM",
                "DAWOOD BHAI",
                "IBRAHIM SHAIKH MOHD ANIS ",
                "SHAIKH ISMAIL ABDUL ",
                "HIZRAT ",
                "SHEIKH FAROOQI ",
                "BADA SETH",
                "BADA BHAI",
                "IQBAL BHAI",
                "MUCCHAD",
                "HAJI SAHAB"
            ],
            "place_of_birth": "Kher, Ratnagiri, Maharashtra, India",
            "date_of_birth": "26-Dec-55",
            "nationality": "India",
            "origin": "DTTOT",
            "country_code": "IN"
        }
    ],
    "id": "0f126904-9c35-45b8-9165-415eedadde54"
}

CFT Response Schema

Parameter	Description
id	string (required) Unique Response ID
request_name	string (required) Request Name
results	array (required) Array of result objects containing potential matches

Result Object Schema

Parameter	Description
aliases	array (optional) Aliases of the person
country_code	string (optional) ISO 3166-2 country code of the person's nationality
date_of_birth	string (optional) Date of birth according to official database
name	string (required) Canonical name
nationality	string (optional) Person's nationality according to official database
origin	string (required) Government data source
pid	string (required) Iluma unique person id
place_of_birth	string (optional) Place of birth according to official database

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

Document OCR Capture: Download Captured Document Using Link

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

Document OCR Capture: Download Captured Document Using Link - 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

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