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. You’re posting all required data in the correct Dukcapil Validation API

  2. You’re handling Dukcapil VAlidation API response correctly

  3. Your face verification purpose in the IdentifAI AI performance with your defined data.

The key differences between sandbox and live checks are:

  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. Sandbox check results are pre-determined for the predefined input, but you can get real similarity results by enrolling images to the sandbox environment.

  3. sandbox applicants are isolated from the live environment.

  4. you won't be charged for checks in the sandbox, but we apply a rate limit for the real use case on enrollment (10 images for an account) and face matching 10 hit/24 hours.

To use the sandbox, you need to generate a sandbox access key and secret key in your IdentifAI Dashboard.

the rate limit is only applicable for real data from Predetermined Face by Enrollment. Each account gets 10 enrollment quota images to store biometrics data and 10 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. To get similarity result using our predertemined input, please use these use case:

    1. Sample photo1.jpg paired with NIK 3275052806930015

    2. Sample photo2.jpg paired with NIK 3174054110970002

  2. To get error response please use these use case

    • NIK 1111111111111111 you will get error response invalid Response from Dukcapil

    • NIK 0000000000000000 you will get response error gateway not responding

  3. To check our face recognition performance, you can use Predetermined Face by Enrollment. Using the Enrollment API you will get the 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
Dukcapil Validation Sandbox API

https://api.cloud.nodeflux.io/v1/analytics/dukcapil-validation
This endpoint allows you to get a free trial Dukcapil Validation for integration of this endpoint to hit the sandbox environment. You do not need to do authorization to use this particular Sandbox API.
Request
Response
Request
Headers
Authorization
required
string
"authorization key fromm sandbox access key "
x-nodeflux-timestamp
required
string
"x-nodeflux-timestamp from authorization"
Content-Type
required
string
application/json
Body Parameters
images
required
string
The base64 encoded image jpeg string and it should follow the data URI scheme format
nik
required
string
16 digit of NIK (Citizen ID number)
transaction_id
required
string
random transaction-id
transaction_source
required
string
Device for requesting API
Response
200: OK
Face Matching Success
{
"job": {
"id": <job_id>,
"result": {
"status": "success",
"analytic_type": "DUKCAPIL_VALIDATION",
"result": [
{
"dukcapil_validation": {
"similarity": 0.8
}
}
]
}
},
"message": "Dukcapil Validation Success",
"ok": true
}

Request Body

The request body should follow this format:

{
"additional_params":{
"nik": "{16 digits of NIK}",
"transaction_id": "{random digit}",
"transaction_source": "{device}"
},
"images": [
"{INSERT_JPEG_IMAGE_AS_BASE64_STRING_FOR_SELFIE_PHOTO}"
]
}

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. Sample photo1.jpg paired with NIK 3275052806930015

  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:

{
"job": {
"id": <job_id>,
"result": {
"status": "success",
"analytic_type": "DUKCAPIL_VALIDATION",
"result": [
{
"dukcapil_validation": {
"similarity": 0.8
}
}
]
}
},
"message": "Dukcapil Validation Success",
"ok": true
}

Predetermined Error Response Example

4xx: Invalid Response from Gateway

To test the negative response for error code 4xx Invalid Response from Gateway, input this NIK:1111111111111111, then you will get this response:

{
"job": {
"id": <job_id>,
"result": {
"status": "incompleted",
"analytic_type": "DUKCAPIL_VALIDATION",
"result": []
}
},
"message": "Invalid Response from Gateway",
"ok": false
}

5xx: Dukcapil Gateway Not Responding

To test the negative response for error code 5xx Dukcapil Gateway Not Responding, input this NIK:0000000000000000, then you will get this response:

{
"job": {
"id": <job_id>,
"result": {
"status": "failed",
"analytic_type": "DUKCAPIL_VALIDATION",
"result": []
}
},
"message": "Gateway not Responding",
"ok": false
}

Predetermined Face by Enrollment

Using this API you can enroll your own data to 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 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
Sandbox Predetermined Face Enrollment

https://cloud.nodeflux.io/sandbox/analytics/create-face-enrollment
This method is used to enroll your face data.
Request
Response
Request
Body Parameters
image
required
string
base64 JPEG/JPG image format
nik
required
string
16 digits of Indonesian citizen ID number
Response
200: OK
{
"message": "Face enrolled successfully",
"nik": "<nik>",
"ok": true
}

Example Body Request

{
"nik": "3276020807980010",
"image": "<image base64>"
}