Migrate to New API Dukcapil Validation
Dukcapil released new flow for the encryption rule and method, we suggest you to migrate on this API to get better encryption method and the performance.

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 on page https://dashboard.identifai.id/solution/dukcapil-validation
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 Url Gateway
The unique url registered from Dukcapil
For privacy and security consent, the submitted credential will be encrypted in our system.
Dashboard look to complete Service Administration

Request Face Matching Service

API Sequence Diagram of Dukcapil Validation Service
  1. 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. 1.
      User ID, Password, and NIK information is encrypted (please check our encryption note below).
  2. 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. 3.
    NODEFLUX GATEWAY forwards the Client requests to DUKCAPIL GATEWAY.
  4. 4.
    Before entering into the matching process on the FACE MATCHING SERVER, Dukcapil decrypts payload parameter: User ID, Password, and NIK;
  5. 5.
    After the decryption process, the NIK information and Face Photo are sent to the FACE MATCHING SERVER for the matching process;
  6. 6.
    The face matching process is carried out on the FACE MATCHING SERVER will return similarity value.
  7. 7.
    The similarity value is sent from MATCHING SERVER to DUKCAPIL GATEWAY;
  8. 8.
    Nodeflux Gateway will return job_id to the client.
  9. 9.
    To get the result, the client should Request GET status by job_id.
  10. 10.
    Nodeflux Gateway will return the similarity result.
Encryption method for NIK and the credential
Upon successful registration, you will receive a public key (in .pem file format) from Dukcapil. You will need the key to encrypt data on a few parameters, including NIK, dukcapil:user_id, and dukcapil:password using RSA public-key encryption. These encrypted data SHOULD be converted into base64 format prior to sending the request.

Asynchronous API Request Method

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": "{encrypted 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
"ip_address":"{registered IP address from Dukcapil}"
10
}
11
},
12
"images": [
13
"{INSERT_JPEG_IMAGE_AS_BASE64_WITH_URI_FORMAT}"
14
]
15
}
Copied!
1
{
2
"additional_params":{
3
"nik": "{encrypted 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
"ip_address":"{registered IP address from Dukcapil}"
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 200 KB 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.

Get The Result from Asynchronous API

Send a GET request to https://api.cloud.nodeflux.io/v1/jobs/{job_id}.
job_id is the one you will receive when posting a job. For example:
1
{
2
"job": {
3
"id": "id": "a-very-long-job-id", // <--- this is the job_id you will use
4
"result": {...}
5
},
6
"message": "Job successfully submitted!",
7
"ok": true
8
}
Copied!
Key
Value
Content-type
application/json
Authorization
Your authorization key
x-nodeflux-timestamp
x-nodeflux-timestamp from the Authorization API.

Example Success Response

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

Example Error Response

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": "401 - Insufficient rights to use the service",
11
"ok": false
12
}
Copied!

Bad request

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

Wrong NIK format

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

No face is detected or There are more than a face in a frame

1
{
2
"job": {
3
"id": "<job_id>",
4
"result": {
5
"status": "incompleted",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "6019 - Please ensure there is only one face is present",
11
"ok": true
12
}
Copied!

Wrong JPEG image format

1
{
2
"code": "unsupported-media-type",
3
"errors": [
4
"Invalid base64 jpeg/jpg string, please use valid data URI scheme for jpeg/jpg"
5
],
6
"message": "Invalid base64 jpeg/jpg string, please use valid data URI scheme for jpeg/jpg",
7
"ok": false
8
}
Copied!

Wrong Dukcapil credential

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

Unencrypted credential parameter or NIK parameter

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

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!

Insufficient quota from Dukcapil

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

Wrong IP Address

1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "failed",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "5003 - Wrong IP address",
11
"ok": false
12
}
Copied!

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": "500 - Invalid Response from Gateway",
11
"ok": false
12
}
Copied!

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!

Synchronous API Request Method

post
https://api.cloud.nodeflux.io
/syncv2/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": "{encrypted 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
"ip_address":"{registered IP address from Dukcapil}"
10
}
11
},
12
"images": [
13
"{INSERT_JPEG_IMAGE_AS_BASE64_WITH_URI_FORMAT}"
14
]
15
}
Copied!
1
{
2
"additional_params":{
3
"nik": "{encrypted 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
"ip_address":"{registered IP address from Dukcapil}"
10
}
11
},
12
"images": [
13
"{INSERT_JPEG_IMAGE_AS_BASE64_WITH_URI_FORMAT}"
14
]
15
"client_ref": "client124"
16
}
Copied!

Example Success Response

1
{
2
"analytic_type": "DUKCAPIL_VALIDATION",
3
"job_id": "<job_id>",
4
"message": "6019 - Dukcapil Validation Success",
5
"ok": true,
6
"result": [
7
{
8
"face_match": {
9
"similarity": 0.95147463157894736,
10
"remaining_quota": 10
11
}
12
}
13
],
14
"status": "success"
15
}
Copied!

Example Error Response

Unauthorized access key

Unauthorized credential
1
{
2
"job_id": <job_id>,
3
"status": "failed",
4
"analytic_type": "DUKCAPIL_VALIDATION",
5
"result": [],
6
"message": "401 - Insufficient rights to use the service",
7
"ok": false
8
}
Copied!

Bad request

Parameter Missing or Invalid
1
{
2
"job_id": "<job_id>",
3
"status": "failed",
4
"analytic_type": "DUKCAPIL_VALIDATION",
5
"result": [],
6
"message": "5004 - Parameter Missing or Invalid",
7
"ok": true
8
}
Copied!

Wrong NIK format

1
{
2
"job_id": "<job_id>",
3
"status": "success",
4
"analytic_type": "DUKCAPIL_VALIDATION",
5
"result": [
6
"remaining_quota": 0
7
],
8
"message": "6019 - NIK not found, please check your NIK",
9
"ok": true
10
}
Copied!

No face is detected or There are more than a face in a frame

1
{
2
"job_id": "<job_id>",
3
"status": "incompleted",
4
"analytic_type": "DUKCAPIL_VALIDATION",
5
"result": [],
6
"message": "6019 - Please ensure there is only one face is present",
7
"ok": true
8
}
Copied!

Wrong JPEG image format

1
{
2
"code": "unsupported-media-type",
3
"errors": [
4
"Invalid base64 jpeg/jpg string, please use valid data URI scheme for jpeg/jpg"
5
],
6
"message": "Invalid base64 jpeg/jpg string, please use valid data URI scheme for jpeg/jpg",
7
"ok": false
8
}
Copied!

Wrong Dukcapil credential

1
{
2
"job_id": "<job_id>",
3
"status": "failed",
4
"analytic_type": "DUKCAPIL_VALIDATION",
5
"result": [],
6
"message": "5001 - Incorrect Combination Dukcapil user_id and password",
7
"ok": true
8
}
9
Copied!

Unencrypted credential parameter or NIK parameter

1
{
2
"job_id": "<job_id>",
3
"status": "failed",
4
"analytic_type": "DUKCAPIL_VALIDATION",
5
"result": []
6
"message": "5006 - Please ensure your parameter value is encrypted",
7
"ok": true
8
}
9
Copied!

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!

Insufficient quota from Dukcapil

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

Wrong IP Address

1
{
2
"job_id": <job_id>,
3
"status": "failed",
4
"analytic_type": "DUKCAPIL_VALIDATION",
5
"result": [],
6
"message": "5003 - Wrong IP address",
7
"ok": false
8
}
Copied!

Dukcapil gateway sends invalid respond

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

Internal Nodeflux server error from

Dukcapil Gateway Not Responding
1
{
2
"job_id": <job_id>,
3
"status": "failed",
4
"analytic_type": "DUKCAPIL_VALIDATION",
5
"result": [],
6
"message": "Gateway not Responding",
7
"ok": false
8
}
Copied!