Introduction

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

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

Learn our APIs with Postman

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

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

Onboarding

Flow Diagram

Onboarding Flow

Integration guide

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

1. Getting set up

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

This section will guide you through three steps

Getting sample code
Authenticating your requests
Setting callbacks

Getting sample code

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

Example code snippet to copy

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

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

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

Authenticating your requests

Example: Using the development API Key in this API documentation

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw

Option 1: Use the functionality built into your request library

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

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

Option 2: Manually construct the Authorization header for basic auth

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

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw:

Next, Base64 encode the colon appended key to get

aWx1bWFfZGV2ZWxvcG1lbnRfRlg0ZjBNNXN4RGdrNXFGeVpuazYwWmVuZ0FmQTlvMzF4M2VjZDI5dmloamM0Vmh5SjhGY2xaaEhqanc6

Then construct your API requests with the Authorization header

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

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

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

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

Setting callbacks

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

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

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

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

2. Making your first request

Once you

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

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

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

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

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

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

3. Simulating responses

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

Note that:

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

Using "Magic Reply" headers.

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

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

More details.

Authentication

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

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw

First, add a colon at the end

iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw:

Finally, Base64 encode the colon appended key to get

aWx1bWFfZGV2ZWxvcG1lbnRfRlg0ZjBNNXN4RGdrNXFGeVpuazYwWmVuZ0FmQTlvMzF4M2VjZDI5dmloamM0Vmh5SjhGY2xaaEhqanc6

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

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

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

Get API Key

Endpoint: Get API Key

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

Example Get API Key Request

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

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

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

Identity

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

Customer Screening

CFT + PEP Individual

CFT + PEP Request Schema - Individual

This endpoint will let you submit a bundle of primary identifiers for an individual registering to your application. We will scan through global sanctions and politically exposed person lists to return a shortlist of possible matches to you so that you (or your automated decisioning system) can make determinations about whether to onboard the individual.

Endpoint: Perform individual CFT + PEP search

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

Example Request - Individual

curl https://api.iluma.ai/v0/identity/individual_cft_peps \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
        "given_names": "Eko Hadi Salim",
        "user_id":"foo123",
        "nationality": "ID",
        "score_threshold": 90,
        "scopes": ["PEP"]
    }'

Parameter	Description
reference_id	string (optional) Your identifier for this request
user_id	string (required) The unique user id for this individual in your systems
given_names	string (required) The given name(s) that will be used for name matching purposes
surname	string (optional) Any known surname(s) for the individual. If provided, these will increase our name matching performance
nationality	string (required) The country of birth or citizenship of the individual. ISO 3166-2 country code
scopes	array (required) Specifies what scope of data sources will be searched using this endpoint. Supported values are `PEP`, `SANCTION`, `OTHER`. `OTHER` includes Adverse Media sources.
addresses	array (optional) Any known addresses (home or work) of the individual. Each address object should have the following format: *country* ISO 3166-2 country code *street_line1* Line 1 of street address e.g., building name and apartment number *street_line2* Line 2 of street address e.g., street number and name *city* City of address *province* Province of address *state* State of address *postal_code* Zip or Postal code of address *category* Address type `HOME`, `WORK` or `PROVINCIAL`. We support Provincial homes to differentiate when the individual has a week-day home address in a city and returns to a family home in the provinces on weekends or holidays
date_of_birth	string (optional) YYYY-MM-DD formatted string
phone_number	string (optional) Mobile number of the individual in E.164 format
email	string (optional) Email address of the individual
gender	string (optional) The gender of the individual you are searching for. Supported values are `FEMALE`, `MALE`, `OTHER`
score_threshold	integer (optional) The minimum score threshold below which we will filter results. The minimum score allowed is 50, and the default score is 85 if not specified

Example Response - Individual

{
    "created": "2022-02-10T18:55:02.061Z",
    "updated": "2022-02-10T18:55:02.840Z",
    "id": "cftpi_05e27fc2-ac76-4307-9f46-36179abb7a6d",
    "reference_id": null,
    "user_id": "foo123",
    "phone_number": null,
    "email": null,
    "addresses": [],
    "scopes": [
        "PEP"
    ],
    "score_threshold": 90,
    "status": "COMPLETED",
    "given_names": "Eko Hadi Salim",
    "surname": null,
    "nationality": "ID",
    "date_of_birth": null,
    "gender": null,
    "results": [
      {
          "id": "2dc667a4-d232-4d51-a561-631ce966fb2c",
          "names": [
              "Eko Hadi Salim"
          ],
          "score": 100,
          "scopes": [
              "OTHER",
              "PEP"
          ],
          "nationalities": [
              "ID"
          ],
          "dates_of_birth": [
              "1943-03-11"
          ]
      }
  ]
}

CFT Response Schema - Individual

Parameter	Description
id	string (required) Our unique identifier of the request for use in later API calls
reference_id	string (required) Your reference id for this request. Will return null if not provided on resource creation
user_id	string (required) Your user id as supplied in the request.
given_names	string (required) The given name(s) that will be used for name matching purposes
surname	string (required) The surname you supplied in this request. Will return null if not provided on resource creation
nationality	string (required) The nationality you supplied in this request. Will return null if not provided on resource creation
addresses	array (required) The array of addresses you supplied in this request. Will return null if not provided on resource creation. Each address object should have the following format: *country* ISO 3166-2 country code *street_line1* Line 1 of street address e.g., building name and apartment number *street_line2* Line 2 of street address e.g., street number and name *city* City of address *province* Province of address *state* State of address *postal_code* Zip or Postal code of address *category* Address type `HOME`, `WORK` or `PROVINCIAL`. We support Provincial homes to differentiate when the individual has a week-day home address in a city and returns to a family home in the provinces on weekends or holidays
date_of_birth	string (required) The date of birth you supplied in this request. Will return null if not provided on resource creation
phone_number	string (required) The phone number you supplied in this request. Will return null if not provided on resource creation
email	string (required) The email you supplied in this request. Will return null if not provided on resource creation
gender	string (required) The array of addresses you supplied in this request. Will return null if not provided on resource creation
scopes	array (required) The array of scopes you supplied in this request. Will return our default search scope if not provided on resource creation
score_threshold	integer (required) The score threshold you supplied in this request. Will return our default setting if not provided on resource creation
status	string (required) The status of the request. Possible values: `COMPLETED`, `FAILED`
failure_reason	string (optional) The reason for the failure. Possible values: `TEMPORARY_NETWORK_ERROR`
results	array (optional) The validation result. Present if status is `COMPLETED`

Result Object Schema - Individual

Parameter	Description
id	string (required) Our unique identifier for this profile
score	integer (required) The fuzzy match similarity between the search profile and this profile
names	array (required) Concatenation of primary known name components on the list
nationalities	array (optional) Array of ISO 3166-2 country code strings of any known nationality of the individual
dates_of_birth	array (optional) Array of date of birth objects according to watchlist. Each object should have the following format: *y (required)* 4 digit year *m (required)* 1-2 digit month *d (required)* 1-2 digit day Partial dates will have values of 0 for the unknown components
scopes	array (required) Array of databases on which the record was found. Possible values are the same as the enum for scopes when making a request.

Endpoint: API Flow

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

CFT + PEP Individual: Get by id

Get individual CFT PEP search

POST https://api.iluma.ai/v0/identity/individual_cft_peps/:id

Example Request - Get Individual by id Request

curl https://api.iluma.ai/v0/identity/individual_cft_peps/cftpi_934b0e7e-2ae8-441d-86af-6304b74d504f \
    -X GET \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw:

Parameter	Description
id	string (required) Request ID as provided in the response object

Example Response - Get Individual by id Request

{
    "created": "2022-02-10T18:55:02.061Z",
    "updated": "2022-02-10T18:55:02.840Z",
    "id": "cftpi_05e27fc2-ac76-4307-9f46-36179abb7a6d",
    "reference_id": null,
    "user_id": "foo123",
    "phone_number": null,
    "email": null,
    "addresses": [],
    "scopes": [
        "PEP"
    ],
    "score_threshold": 90,
    "status": "COMPLETED",
    "given_names": "Eko Hadi Salim",
    "surname": null,
    "nationality": "ID",
    "date_of_birth": null,
    "gender": null,
    "results": [
        {
            "id": "2dc667a4-d232-4d51-a561-631ce966fb2c",
            "names": [
                "Eko Hadi Salim"
            ],
            "score": 100,
            "scopes": [
                "OTHER",
                "PEP"
            ],
            "nationalities": [
                "ID"
            ],
            "dates_of_birth": [
                "1943-03-11"
            ]
      }
  ]
}

Endpoint: API Flow

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

CFT + PEP Entity

CFT + PEP Request Schema - Entity

This endpoint will let you submit a bundle of primary identifiers for a business entity (Company, partnership etc) registering to your application. We will scan through global sanctions and politically exposed person lists to return a shortlist of possible matches to you so that you (or your automated decisioning system) can make determinations about whether to onboard the business entity. Note that PEP checks will be done against known directors and shareholders

Endpoint: Perform entity CFT + PEP search

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

Example Request - Entity

curl https://api.iluma.ai/v0/identity/entity_cft_peps \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "IBM Corporation",
        "user_id": "foo123",
        "business_domicile": "US",
        "score_threshold": 90,
        "scopes": ["PEP"]
    }'

Parameter	Description
reference_id	string (optional) Your identifier for this request
user_id	string (required) The unique user id for this individual in your systems
name	string (required) Legal or trading name of the business
business_domicile	string (required) The country code of the business’ registration
scopes	array (required) Specifies what scope of data sources will be searched using this endpoint. Supported values are `PEP`, `SANCTION`, `OTHER`. `OTHER` includes Adverse Media sources
addresses	array (optional) Array of objects containing any known addresses for the individual. Each object should have the following components: *country* ISO 3166-2 country code *street_line1* Line 1 of street address e.g., building name and apartment number *street_line2* Line 2 of street address e.g., street number and name *city* City of address *province* Province of address *state* State of address *postal_code* Zip or Postal code of address *category* Address type `HOME`, `WORK` or `PROVINCIAL`. We support Provincial homes to differentiate when the individual has a week-day home address in a city and returns to a family home in the provinces on weekends or holidays
date_of_registration	string (optional) Date of business registration if known
phone_number	string (optional) Mobile number of the individual
email	string (optional) Email address of the individual
score_threshold	integer (optional) The minimum score threshold below which we will filter results. The minimum score allowed is 50, and the default score is 85 if not specified

Example Response - Entity

{
    "created": "2022-02-17T21:17:49.917Z",
    "updated": "2022-02-17T21:17:50.712Z",
    "id": "cftpi_934b0e7e-2ae8-441d-86af-6304b74d504f",
    "reference_id": null,
    "user_id": "foo123",
    "addresses": [],
    "scopes": [
        "PEP"
    ],
    "score_threshold": 95,
    "status": "COMPLETED",
    "name": "intel",
    "business_domicile": "US",
    "results": [
        {
            "id": "ed84802c-d73d-4d22-8897-5bc771709073",
            "score": 100,
            "names": [
                "Intel Corp",
                "Intel Corporation"
            ],
            "business_domiciles": [
                "US"
            ],
            "scopes": [
                "OTHER",
                "PEP"
            ]
        }
    ]
}

CFT Response Schema - Entity

Parameter	Description
id	string (required) Our unique identifier of the request for use in later API calls
reference_id	string (required) Your reference id for this request. Will return null if not provided on resource creation
user_id	string (required) Your user id as supplied in the request.
business_name	string (required) The name you supplied in this request.
business_domicile	string (required) The nationality you supplied in this request. Will return null if not provided on resource creation
addresses	array (required) The array of addresses you supplied in this request. Will return null if not provided on resource creation
date_of_registration	string (required) The date of birth you supplied in this request. Will return null if not provided on resource creation
phone_number	string (required) The phone number you supplied in this request. Will return null if not provided on resource creation
email	string (required) The email you supplied in this request. Will return null if not provided on resource creation
gender	string (required) The array of addresses you supplied in this request. Will return null if not provided on resource creation
scopes	array (required) The array of scopes you supplied in this request. Will return our default search scope if not provided on resource creation
score_threshold	integer (required) The score threshold you supplied in this request. Will return our default setting if not provided on resource creation
status	string (required) The status of the request. Possible values: `COMPLETED`, `FAILED`
failure_reason	string (optional) The reason for the failure. Possible values: `TEMPORARY_NETWORK_ERROR`
results	array (optional) The validation result. Present if status is `COMPLETED`

Result Object Schema - Entity

Parameter	Description
id	string (required) Our unique identifier for this profile
score	integer (required) The fuzzy match similarity between the search profile and this profile
names	array (required) Concatenation of primary known name components on the list
business_domiciles	array (optional) Array of ISO 3166-2 country code strings of any known business registration countries
dates_of_registration	array (optional) Array of known registration date objects according to watchlist. Each object should have the following format: *y (required)* 4 digit year *m (required)* 1-2 digit month *d (required)* 1-2 digit day Partial dates will have values of 0 for the unknown components
scopes	array (required) Array of databases on which the record was found. Possible values are the same as the enum for scopes when making a request.

Endpoint: API Flow

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

CFT + PEP Entity: Get by id

Endpoint: Get entity CFT PEP search

POST https://api.iluma.ai/v0/identity/entity_cft_peps/:id

Example Request - Get Entity by id Request

curl https://api.iluma.ai/v0/identity/entity_cft_peps/cftpi_934b0e7e-2ae8-441d-86af-6304b74d504f \
    -X GET \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw:

Parameter	Description
id	string (required) Request ID as provided in the response object

Example Response - Get Entity by id Request

{
    "created": "2022-02-17T21:17:49.917Z",
    "updated": "2022-02-17T21:17:50.712Z",
    "id": "cftpi_934b0e7e-2ae8-441d-86af-6304b74d504f",
    "reference_id": null,
    "user_id": "foo123",
    "addresses": [],
    "scopes": [
        "PEP"
    ],
    "score_threshold": 95,
    "status": "COMPLETED",
    "name": "intel",
    "business_domicile": "US",
    "results": [
        {
            "id": "ed84802c-d73d-4d22-8897-5bc771709073",
            "score": 100,
            "names": [
                "Intel Corp",
                "Intel Corporation"
            ],
            "business_domiciles": [
                "US"
            ],
            "scopes": [
                "OTHER",
                "PEP"
            ]
        }
    ]
}

Endpoint: API Flow

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

CFT + PEP Record: Get by id

Endpoint: Get CFT + PEP record

POST https://api.iluma.ai/v0/identity/cft_pep_listings/:id

Example Request - Get record by id

curl https://api.iluma.ai/v0/identity/entity_cft_peps/2dc667a4-d232-4d51-a561-631ce966fb2c \
    -X GET \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw:

Parameter	Description
id	string (required) The ID as provided in the result from the search, i.e., body.results[x].id

Example Response - Get record by id

{
  "id": "2dc667a4-d232-4d51-a561-631ce966fb2c",
  "names": [
    "Eko Hadi Salim"
  ],
  "score": 100,
  "scopes": [
    "OTHER",
    "PEP"
  ],
  "nationalities": [
    "ID"
  ],
  "dates_of_birth": [
    "1943-03-11"
  ]
}

Endpoint: API Flow

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

KTP Biometrics Verification

Endpoint: id card verifications

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

Example Id card verifications Request

curl https://api.iluma.ai/v0/identity/id_card_verifications \
    -X POST \
    -u iluma_development_FX4f0M5sxDgk5qFyZnk60ZengAfA9o31x3ecd29vihjc4VhyJ8FclZhHjjw: \
    -F 'name="penito kristian"' \
    -F 'id_card_number="3275031210930027"' \
    -F 'birthdate="12-10-1991"' \
    -F 'birthplace="Ketapang"' \
    -F 'address="Alinda kencana blok E"' \
    -F 'selfie=@"/path/to/file.png"''

The KTP verification endpoint exists to help you check if a given KTP or NIK number exists in the official records of the Indonesian government and checks if the selfie matches. In addition, if you submit non-essential card data, we can verify that it matches the official records.

Versions

You are currently viewing API version V0. New version is available! Click here to view newer versions.

Id card verifications Request

Parameter	Description
name	string (required) Name of the individual as per the KTP card Min - `2 characters`, Max - `100 characters`
id_card_number	string (required) The national identity card number as per the KTP card
birthdate	string (optional) Date of birth as shown on the KTP card Format `DD-MM-YYYY` string
birthplace	string (optional) End-user's birth place as shown on the KTP card
address	string (optional) End-user’s address as shown on the KTP card
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: `500KB`. Minimum file size: `100KB`, `500x500 pixels`

Id card verifications Response

Example Id card verifications Response - Success (Found)

{
  "id": "idvr_c2b7a96a-9dc2-491e-b274-71c84b6e25d1",
  "created": "2022-03-21T12:24:42.480Z",
  "updated": "2022-03-21T12:24:42.480Z",
  "id_card_number": "3275031210930027",
  "name": "penito kristian",
  "birthdate": "12-10-1990",
  "birthplace": "ketapang",
  "address": "Alinda kencana blok E",
  "status": "COMPLETED",
  "is_found": true,
  "result": {
    "seflie_score": 100,
    "is_name_match": true,
    "is_birthdate_match": true,
    "is_birthplace_match": true,
    "is_address_match": true
    }
}

Example Id card verifications Response - Success (Not Found)

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

Example Id card verifications Response - Failure

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

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

Id card verifications Schema

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

Result Object Schema

Parameter	Description
is_name_match	boolean (required) If the NIK was found, whether the name was an exact match with the record Dukcapil holds for this NIK
is_birthdate_match	boolean (optional) If the NIK was found, whether the date of birth was an exact match with the record Dukcapil holds for this NIK
is_birthplace_match	boolean (optional) If the NIK was found, whether the place of birth was an exact match with the record Dukcapil holds for this NIK
is_address_match	boolean (optional) If the NIK was found, whether the address was a fuzzy match with the record Dukcapil holds for this NIK
selfie_score	number (required) If the NIK was found, how similar the submitted selfie was with the image Dukcapil holds for this NIK

Endpoint: API Flow

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

Id card verifications 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

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