IdentifAI Dukcapil Validation
IdentifAI Dukcapil Validation aims to validate the facial biometric identity of an individual through the National ID Database (Dukcapil). We can do this thanks to our cutting-edge technology and Agreement with Indonesia's Ministry of Home Affairs who oversees the National ID Database.
Below are some of our key technology & platform:
    Face Match [1:1] --> Comparing two photos containing facial biometric information, through AI and Face Recognition Technology, we can define their level of similarities.
    Our computational platform for face-matching is operated on-premise in Dukcapil's environment.
    The Shared-Platform (Platform Bersama) is an interface managed by the appointed agency (where Nodeflux is one of the appointees) and served as a bridge in validating the data to Dukcapil's National ID Database.

Prerequisite

Please ensure you are authorized to access the Dukcapil Platform Bersama. The Dukcapil credentials data are identifier data used to validate that users actually get access rights to use the Dukcapil Platform Bersama. Without sending the credential data, the Rest API call will be rejected by the system. You need to fill your credentials in the IdentifAI dashboard such as:
Credential Data
Explanation
Dukcapil Agreement Number (Nomor PKS)
The agreement number is stated in your Dukcapil Agreement letter for accessing face bimetric service
Dukcapil Agreement expiration date
Expiration date of Dukcapil Agreement that state in the agreement letter
Dukcapil Customer ID
The unique profile name of and institution that has been approved by Dukcapil
Dukcapil User ID
The unique username of and institution that is given by Dukcapil
Password
The password is given by Dukcapil as an authorization of rights service access.
For the privacy and the security consent, the submitted credential will be encrypted in our system
Credentials Dashboard

API Sequence Diagram

To use the service, you have to encrypt your image parameter and the credential for security purpose. Here are the sequences of how to do encryption and use the API.

Request Encryption

    1.
    Client requests payload parameters encryption API directly to DUKCAPIL GATEWAY with clients’ private connection.
    2.
    DUKCAPIL GATEWAY provides an encrypted parameter to the Client.
    3.
    The encryption step will return encrypted credential and image

post
http://172.16.160.175:8000/pb1-util
/encrypt
Encryption Parameter

Request Example

1
{
2
"user_id": "xxxxxx",
3
"password": "xxxxxxxx",
4
"image": "BASE64_JPEG"
5
}
Copied!

Response Example

1
{
2
"image": "F6p3rfKNqM8",
3
"user_id": "GWwPxhlV8I0",
4
"password": "XFv-n0PdeNKgh4y4-vSjhQ"
5
}
6
Copied!

Request Face Matching Service

    1.
    Face matching request on Platform Bersama is sent via Nodeflux Gateway (IdentifAI Dukcapil Validation API) which is made by each client containing information on NIK, User ID, Password, and Face Photo.
      1.
      User ID, Password, and Face Photo information is encrypted from step 1,
      2.
      NIK information is sent without encryption.
    2.
    Nodeflux gateway checks the service activation and registered client's Dukcapil Gateway URL. The URL information will be retrieved from your dashboard. Please complete your account information by filling authorized URL from Dukcapil on dashboard.identifai.id.
    3.
    NODEFLUX GATEWAY forwards the Client requests to DUKCAPIL GATEWAY.
    4.
    Before entering into the matching process on the FACE MATCHING SERVER, Dukcapil decrypts payload parameter: User ID, Password, and Face Photo information;
    5.
    After the decryption process, the NIK information and Face Photo are sent to the FACE MATCHING SERVER for the matching process;
    6.
    The face matching process is carried out on the FACE MATCHING SERVER will return similarity value.
    7.
    The similarity value is sent from MATCHING SERVER to DUKCAPIL GATEWAY;
    8.
    Nodeflux Gateway will return job_id to the client.
    9.
    To get the result, the client should Request GET status by job_id.
    10.
    Nodeflux Gateway will return the similarity result.
post
https://api.cloud.nodeflux.io
/v1/analytics/dukcapil-validation
Dukcapil Validation API

Request Body

The request body should follow this format:
Required Fields Only
All Fields
1
{
2
"additional_params":{
3
"nik": "{16 digits of NIK}",
4
"transaction_id": "{random digit}",
5
"transaction_source": "{device}",
6
"dukcapil":{
7
"user_id": "{encrypted_user_id}",
8
"password": "{encrypted_password}",
9
"image":"{INSERT_ENCRYPTED_PLAIN_BASE64_IMAGE_DATA}"
10
}
11
},
12
"images": [
13
"{INSERT_JPEG_IMAGE_AS_BASE64_WITH_URI_FORMAT}"
14
]
15
}
Copied!
1
{
2
"additional_params":{
3
"nik": "{16 digits of NIK}",
4
"transaction_id": "{random digit}",
5
"transaction_source": "{device}",
6
"dukcapil":{
7
"user_id": "{encrypted_user_id}",
8
"password": "{encrypted_password}",
9
"image":"{INSERT_ENCRYPTED_PLAIN_BASE64_IMAGE_DATA}"
10
}
11
},
12
"images": [
13
"{INSERT_JPEG_IMAGE_AS_BASE64_WITH_URI_FORMAT}"
14
]
15
"client_ref": "client124"
16
}
Copied!
Note for image input:
    The maximum allowed image file size is 1 MB per image The image should be represented in base64 data based on a.JPG format. You can use any online jpg-to-base64 encoder to get the base64 data.
    Please provide a self-portrait or selfie image and make sure only a single face is presented on the frame.
    For more detail about image configuration please check the page Image Configuration Guideline.

Example Success Response

1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "success",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": [
8
{
9
"dukcapil_validation": {
10
"similarity": 0.8
11
}
12
}
13
]
14
}
15
},
16
"message": "Dukcapil Validation Success",
17
"ok": true
18
}
Copied!

Example Error Response

4xx: Unauthorized access key

Unauthorized credential
1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "incompleted",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "Insufficient rights to use the service",
11
"ok": false
12
}
Copied!

4xx: Bad request

Parameter Missing or Invalid
1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "incompleted",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "Parameter Missing or Invalid",
11
"ok": false
12
}
Copied!

4xx: Image not found

No image in request payload
1
{
2
"code": "invalid-argument",
3
"errors": [
4
"images cannot be empty"
5
],
6
"message": "Required field(s) is not supplied or having an invalid type please check again",
7
"ok": false
8
}
Copied!

4xx: Wrong NIK format

1
{
2
"job": {
3
"id": "<job_id>",
4
"result": {
5
"status": "incompleted",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "NIK format is invalid",
11
"ok": true
12
}
Copied!

4xx: NIK not found

1
{
2
"job": {
3
"id": "<job_id",
4
"result": {
5
"status": "incompleted",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "NIK is not found, please check your NIK",
11
"ok": true
12
}
13
Copied!

4xx: Wrong JPEG image format

1
{
2
"job": {
3
"id": "<job_id>",
4
"result": {
5
"status": "incompleted",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "Please ensure image format is JPEG",
11
"ok": true
12
}
Copied!

4xx: Wrong Dukcapil credential

1
{
2
"job": {
3
"id": "<job_id>",
4
"result": {
5
"status": "incompleted",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "Incorrect combination Dukcapil user_id and password",
11
"ok": true
12
}
13
Copied!

4xx: Unencrypted image or unencrypted credential parameter

1
{
2
"job": {
3
"id": "<job_id>",
4
"result": {
5
"status": "incompleted",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "Please ensure your parameter value is encrypted",
11
"ok": true
12
}
13
Copied!

4xx: No encrypted image

1
{
2
"job": {
3
"id": "cb7e7c569bbe72d6c6b3aa4b9ed6011ab3b28bbbad29e042GIYDEMJNGA4C2MJZ",
4
"result": {
5
"status": "failed",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "Unable to read image data, please provide image data on the correct field",
11
"ok": true
12
}
13
Copied!

4xx: No image value on image parameter

1
{
2
"analytic": "DUKCAPIL_VALIDATION",
3
"code": "invalid-argument",
4
"errors": [
5
"Please provide 1 image(s) for DUKCAPIL_VALIDATION to proceed"
6
],
7
"message": "The total image(s) provided is not valid",
8
"ok": false
9
}
10
Copied!

4xx: Insufficient quota from Dukcapil

1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "incompleted",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "Your daily quota hit on Dukcapil Gateway is insufficient, please contact Dukcapil for additional Quota",
11
"ok": false
12
}
13
Copied!

5xx: NIK Data not Found

Note: The NIK data might be not found because the image data has not been extracted yet on our database. However, we will do regularly update if there is any new citizen data on Dukcapil. This error is not charged by our system.
1
{
2
"job": {
3
"id": "<job_id>",
4
"result": {
5
"status": "failed",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "NIK data not found",
11
"ok": true
12
}
Copied!

5xx: Dukcapil gateway sends invalid respond

1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "failed",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "Invalid Response from Gateway",
11
"ok": false
12
}
Copied!

5xx: Internal Nodeflux server error from

Dukcapil Gateway Not Responding
1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "failed",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "Gateway not Responding",
11
"ok": false
12
}
Copied!
Last modified 11d ago