Dukcapil With FaceMatch API

This document highlights the Dukcapil with Face Match API details.

API Description

Objective

The Dukcapil with Face Match API verifies an Indonesian ID card by matching the provided selfie with official records. It returns a match result and score in the response.

Input	Output
The selfie and Indonesian ID card number of the user	The face match results, including the match status (true/false) and score

info

Dukcapil is the Indonesian government institution that handles citizenship-related services such as issuing passports, birth certificates, death certificates, and more.

API URL

https://ind-thomas.hyperverge.co/v1/dukcapilWithFacematch

API Endpoint

dukcapilWithFacematch

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Input

The following table outlines the parameter required in the API's request body:

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
id	The Indonesian ID card number of the user	Mandatory	Not Applicable	Not Applicable
image	The selfie of the ID card holder	Mandatory	Allowed formats: png, jpg, jpeg, pdf	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind.thomas.hyperverge.co/v1/dukcapilWithFacematch' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "id": "<Enter_the_ID>",
    "image": "<Enter_the_base64_image_data>"
}'

Success Response

The following code snippet demonstrates a success response from the API:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "message": "<Message_About_The_Result>",
    "details": {
      "score": "<Score>",
      "match": "<Match_status>",
    },
     "s3Url": "<S3_URL_link>"
    },
  },
  "metaData": {
    "requestId": "<Unique_Request_Identifier>",
    "transactionId": "<Unique_Transaction_Identifier>"
  }

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the API response
statusCode	integer	The HTTP status code of the response
result	object	The object containing the verification results
result.status	string	The status of the verification process
result.message	object	The object containing the match results
result.message.score	integer	The confidence score of the face match
result.message.match	boolean	Indicates whether the face match was successful
result.s3Url	string	The URL of the input image stored in S3
metaData	object	The object containing metadata for the request
metaData.requestId	string	The unique identifier for the request
metaData.transactionId	string	The transaction ID associated with the request

Failure Responses

The following are failure responses from the API:

Invalid NIK format

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "status": "INVALID_REQUEST",
        "message": "nik format is not valid"
    }
}

Face Detection Failure

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "status": "RETRY_LATER",
        "message": "input image detect face fail"
    }
}

Invalid Image Size

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "status": "IMAGE_INVALID_SIZE",
        "message": "image larger than 2M"
    }
}

Error Responses

The following are the error responses from the API:

Missing Input Parameter: Image

{
    "message": "Image not found",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Input Validation Error- Invalid Image Type

{
    "message": "Invalid file type for: image",
    "statusCode": 400,
    "status": "failure"
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Internal Server Error

{
    "message": "Internal Server Error",
    "statusCode": 500,
    "status": "failure"
}

Failure and Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message. The following table lists all error responses:

Status Code	Error Message	Error Description
200	nik format* is not valid	The request has an invalid nik format
200	input image detect face fail	The request is invalid as it did not detect any face
200	image larger than 2M	The request is invalid as the image size is larger than 2MB
400	Image not found	The selfie of the user is missing in the API request made
400	Invalid file type for: image	The image entered is not one of the required formats: jpeg, jpg, png, or pdf
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution

info

*nik format: A NIK format refers to the specific format used for an Indonesian citizen's identity card number, called "Nomor Induk Kependudukan" (NIK), which is a 16-digit code consisting of a region code, date of birth, and a serial number; essentially, it's the Indonesian equivalent of a social security number, displayed on their KTP (Kartu Tanda Penduduk) or identity card.