Dukcapil Validation Sandbox API
Only for integration test. Sandbox check results are pre-determined you won't be charged for checks in sandbox. Access Key and token are generated from IdentifAI admin.

Sandbox and Live Differences

This Sandbox API is only applicable for integration testing only, not intended for live production. Because this Sandbox API is intended for simulation purposes, the payload response for the similarity result is defined by predefined input.
You can use the sandbox API to simulate API request and to check:
  1. 1.
    You’re posting all required data in the correct Dukcapil Validation API
  2. 2.
    You’re handling the Dukcapil VAlidation API response correctly
  3. 3.
    Your face verification purpose in the IdentifAI AI performance with your defined data.

The key differences between sandbox and live checks are:

  1. 1.
    sandbox check data is not processed by the Dukcapil gateway service — this means that sandbox responses are faster than live responses and the result of similarity comes from Nodeflux Server.
  2. 2.
    Sandbox check results are pre-determined for the predefined input, but you can get real similarity score results by enrolling images in the sandbox environment.
  3. 3.
    sandbox applicants are isolated from the live environment.
  4. 4.
    you won't be charged for checks in the sandbox, but we apply a rate limit for the real use case on enrollment (200 images for an account) and face matching 200 hits/24 hours. It counts from your first hit on that day.
To use the sandbox, you need to generate a sandbox access key and secret key in your IdentifAI Dashboard. The access key sandbox is only valid for Dukcapil Validation, Create Face Enrollment, and Face Match Enrollment.
If you use access key sandbox, the job id will give the prefix 'sandbox', for example: sandbox-069336cfd6d8809de1b0d85fae9d106c5b59
the rate limit is only applicable for real data from Predetermined Face by Enrollment. Each account gets 200 enrollment quota images to store biometrics data and 200 hits per-24 hours for face matching validation.

Predetermined Response

To help you check the integration in the sandbox API, you can trigger by using these predetermined sample photos and the pre-determined NIK (Indonesia Citizen Number).
  1. 1.
    To get similarity result using our predertemined input, please use these use case:
    1. 1.
      Sample photo1.jpg paired with NIK 3275052806930015
    2. 2.
      Sample photo2.jpg paired with NIK 3174054110970002
  2. 2.
    To get error response please use these use case
    • NIK 0000000000000000 you will get a response 500 - Invalid Response from Gateway
    • NIK 1111111111111111 you will get an error response 6019 - NIK not found, please check your NIK
    • NIK 2222222222222222 you will get a response similarity score 0.
    • NIK 3333333333333333 you will get a response 5004 - Parameter Missing or Invalid.
  3. 3.
    To check our face recognition performance, you can use Predetermined Face by Enrollment. Using the Enrollment API you will get a real similarity result.

Generate Authorization Key

For the sandbox API, it has a dedicated access key and secret key, you can not modify the account. Visit your dashboard to get the access key on the tab Access Key for Sandbox API Dukcapil Validation.
Sandbox Access Key and Secret Key Dashboard
Please cek the guideline for generate access key.
post
https://api.cloud.nodeflux.io
/v1/analytics/dukcapil-validation
Dukcapil Validation Sandbox API

Request Body

The request body should follow this format:
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
"ip_address":"{insert dummy ip address}"
10
}
11
},
12
"images": [
13
"{INSERT_JPEG_IMAGE_AS_BASE64_WITH_URI_FORMAT}"
14
]
15
}
Copied!
The base64 encoded jpeg string should follow the data URI scheme format. See below:
data:[<media type>][;base64],<data>

Defined Predetermined Use Case

Predetermined Positive Response

To help you test integration in the sandbox API, you can trigger pre-determined positive responses by using sample images and NIK below:
  1. 1.
    Sample photo1.jpg paired with NIK 3275052806930015
  2. 2.
    Sample photo2.jpg paired with NIK 3174054110970002
photo1.jpg paired with NIK 3275052806930015
photo2.jpg paired with 3174054110970002
For success response, you will get similarity result of the photos:
1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "success",
6
"analytic_type": "DUKCAPIL_VALIDATION_SANDBOX",
7
"result": [
8
{
9
"dukcapil_validation": {
10
"similarity": 0.8
11
}
12
}
13
]
14
}
15
},
16
"message": "6018 - Dukcapil Validation Success",
17
"ok": true
18
}
Copied!

Predetermined Error Response Example

5Invalid Response from Gateway

To test the negative response for error Invalid Response from Gateway, input this NIK:00000000000000, then you will get this response:
1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "incompleted",
6
"analytic_type": "DUKCAPIL_VALIDATION_SANDBOX",
7
"result": []
8
}
9
},
10
"message": "500 - Invalid Response from Gateway",
11
"ok": false
12
}
Copied!

Dukcapil Gateway Not Responding

To test the negative response for NIK not found, input this NIK:1111111111111111, then you will get this response:
1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "failed",
6
"analytic_type": "DUKCAPIL_VALIDATION",
7
"result": []
8
}
9
},
10
"message": "6019 - NIK not found, please check your NIK",
11
"ok": false
12
}
Copied!

Predetermined Face by Enrollment

Using this API you can enroll your own data in our sandbox. By using the image that enrolled before, you can check the real face matching process between to photos that you defined by storing the NIK as an identifier for verification.
The rate limit is applicable for the Predetermined Face by Enrollment because it is use our AI computational. Each account gets 10 enrollment quota images to store biometrics data and 10 hits per-24 hours for face matching validation, but for checking the integration you can still use our defined predetermined use case.
post
https://cloud.nodeflux.io/
sandbox/analytics/create-face-enrollment
Sandbox Predetermined Face Enrollment
Example Body Request
1
{
2
"nik": "3276020807980010",
3
"image": "<image base64>"
4
}
Copied!
Example success response
1
{
2
"job": {
3
"id": "sandbox-1b8df0dceb00ea657da6bb45e4c6d69656517c9c9be834d1GIYDEMJNGEZC2MRR",
4
"result": {
5
"status": "success",
6
"analytic_type": "CREATE_FACE_ENROLLMENT_SANDBOX",
7
"result": [
8
{
9
"create_face_enrollment": {
10
"face_id": "3173073005910010",
11
"variation": "11895442083454394549",
12
"bounding_box": {
13
"top": 0.2904913127422333,
14
"left": 0.763171911239624,
15
"width": 0.17411309480667114,
16
"height": 0.3280334770679474
17
}
18
}
19
}
20
]
21
}
22
},
23
"message": "Face Enrollment Success",
24
"ok": true
25
}
Copied!

Error Response

Unauthorized access key

Unauthorized credential
1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "incompleted",
6
"analytic_type": "DUKCAPIL_VALIDATION_SANDBOX",
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_SANDBOX",
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_SANDBOX",
7
"result": []
8
}
9
},
10
"message": "6019 - NIK not found, please check your NIK",
11
"ok": true
12
}
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_SANDBOX",
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_SANDBOX",
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_SANDBOX",
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_SANDBOX 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_SANDBOX",
7
"result": []
8
}
9
},
10
"message": "5002 - Your daily quota hit on Dukcapil Gateway is insufficient, please contact Dukcapil for additional Quota",
11
"ok": false
12
}
13
Copied!

Wrong IP Address

1
{
2
"job": {
3
"id": <job_id>,
4
"result": {
5
"status": "failed",
6
"analytic_type": "DUKCAPIL_VALIDATION_SANDBOX",
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_SANDBOX",
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_SANDBOX",
7
"result": []
8
}
9
},
10
"message": "Gateway not Responding",
11
"ok": false
12
}
Copied!