Biometric Verification

Face biometric verification to dukcapil database.

This module only support biometric verification for indonesian identity card (KTP)

Endpoints

Method	URL
POST	$synapses/v1/identity/verification/biometric

Headers

Header	Value
Content-Type	application/json
Authorization	Bearer YOUR_API_KEY

Request

Description

Field	Type	Description
identityId (required)	String (len: 16)	Nomor induk kependudukan (NIK).
faceImage (required)	Base64	Image binary encoded in base64 without <data:image/png;>. - Supports: JPG, JPEG, PNG, SVG - Max Size: 1MB

Example

{
    "identityId": "1234567890123456",
    "faceImage": "<base64>"
}

Testing

In the sandbox environment, we only response api call with dummy data. To get valid response data, you can use our production environment instead.

Face Match

You can use identityId = 1234567890123456 to produce face not match result.

Example:

{
    "identityId": "1234567890123456",
    "faceImage": "<base64>"
}

{
    "message": "Identity biometric verification succeeded.",
    "data": {
        "id": "64d07984-81a8-4e79-ad16-a439f5885075",
        "identityId": "1234567890123456",
        "isValid": true,
        "isActive": true,
        "response": {
            "face": true,
            "faceSimilarity": 1.0
        }
    }
}

Face Not Match

You can use any identityId except 1234567890123456 to produce face not match result.

Example:

{
    "identityId": "1234567890111111",
    "faceImage": "<base64>"
}

{
    "message": "Identity biometric verification succeeded.",
    "data": {
        "id": "cfe1732d-bd89-4e97-94c1-b3790a2952c4",
        "identityId": "1234567890111111",
        "isValid": true,
        "isActive": true,
        "response": {
            "face": false,
            "faceSimilarity": 0.24
        }
    }
}

Wrong Identity

You can use any identityId except 1234567890123456 and 1234567890111111 to produce identity not valid result.

{
    "identityId": "1234567890123444",
    "faceImage": "<base64>"
}

{
    "message": "Identity biometric verification succeeded.",
    "data": {
        "id": "f989eae0-59a3-4a04-baac-6f16c8e7b7fd",
        "identityId": "1234567890123444",
        "isValid": false,
        "isActive": false,
        "response": {}
    }
}

Response

Description

Field	Type	Description
id	String	Unique identifier.
identityId	String	Nomor induk kependudukan (NIK).
isValid	Boolean	Return true if identityId is exist in the Dukcapil database.
isActive	Boolean	Return true if identityId is active in the Dukcapil database.
response:face	Boolean	Return true if input face match with the face in dukcapil database. - Default threshold: >= 0.75: True
response:faceSimilarity	Float (0-1)	Similarity between the input face and the face in Dukcapil database.

Example

{
    "message": "Identity biometric verification succeeded.",
    "data": {
        "id": "7d7cb73b-c55a-4e93-b3d0-972058bd9ccd",
        "identityId": "1234567890123456",
        "isValid": false,
        "isActive": false,
        "response": {
            "face": false,
            "faceSimilarity": 0.36
        }
    }
}

Errors

Please read this page <Responses & Errors> to know more about response.

Error 4XX

Error Type

Error Type	Description	Is charged?
invalid_base64_encoding	Invalid base64 encoding.	False
image_too_large	Input image is greater than the maximum size allowed.	False
no_face_detected	No face was detected from the input image or the input image is blurry.	True
request_error	Cannot get response from Dukcapil server.	False

Structure

{
   "errors":{
      "errorId": <log_id:uuid>,
      "errorType": <error_type:str>
   },
   "message": <message:str>
}

Error 5XX

For every 5XX http code response, there will be no charge.