Guidelines
Start typing to search…

API Request & Response

📘

This page is currently under maintenance (16-09-2025)

🎈Endpoint

MethodEndpoint
POSThttps://api.verihubs.com/data-verification/certificate-electronic/verify

🎈Headers

Key

Type

Description

App-ID

String

  • Application ID that generated from Application Menu in Verihubs Client Dashboard.
  • To hit in Testing and Live mode you need a Production Application ID.

API-Key

String

API-Key that generated from Application Menu in Verihubs Client Dashboard that related to specific Application ID.

You can generate your Application ID and API-Key in the Application page in Verihubs Client Dashboard..

🎈Request

Request Parameter

Parameter

Type

Description

Validation

Example

nik

String

Nomor Induk Kependudukan as stated on the KTP.

  • Must be 16 digits
  • Numeric only
  • Can not start with 0
  • Can not have four consecutive numbers

9171022512990011

name

String

Full name as stated on the KTP.

John Doe

birth_date

String

Birth date as stated on the KTP.

  • Must be in DD-MM-YYYY format
  • Minimum 17 years old counted from the current date to the birth date inputted.

01-01-1901

email

String

Email address that must be unique per NIK.

  • Must be email format (@)
  • Must be unique per NIK for Certificate Electronic generation.

[email protected]

phone

String

Phone number that must be unique per NIK.

  • Use country code
  • Must be a valid phone number

62812010101010101

selfie_photo

String

The same face that registered as the owner of the KTP

  • Format base64
  • Minimum size 100 KB
  • Maximum size 4 MB
  • Minimum pixel 480 x 640 px
  • Maximum pixel 10.000 x 10.000 px

Base64

ktp_photo

String

A full pyshical/digital KTP photo

  • Format base64
  • Minimum size 100 KB
  • Maximum size 2 MB
  • Minimum pixel 480 x 360 px

Base64

reference_id

String

A user inputted unique id to refer to a certain transaction

  • This reference_id can be used to indicate your company’s transaction and must be unique.
  • If the reference_id is not inputted, then Verihubs will generate one for you

SERTEL_123

🎈Response

Response

HTTP Code

Description

200

Successful Transaction; Transaction that is considered successful and has been successfully verified by the data source.

400

  • Invalid Payload; Transaction that is considered failed due to validation errors, an error_field will appear explaining the error.
  • Access Timeout from Datasource; The transaction

401

Authorization Failed; Possible reason:

  • Sandbox App ID and/or API Key used in Production mode transaction.
  • Unmatch App ID and API Key.

403

Forbidden; The transaction is in Testing mode and not enough remaining quota. Possible reason:

  • Electronic Certificate quota
  • Liveness-Sertel quota

429

Too Many Request; Spam Error as the transaction is read as spam, please wait a 10 seconds before re-performing the hit process.

500

  • Internal Server Error in Datasource; The transaction failed due to server error in datasource.
  • Internal Server Error; The transaction failed due to server error in Verihubs.

List of Reject Field

The reject field indicates if a parameter is returned incorrectly after being checked from the data source side.

HTTP Codereject_fieldDefinition
200nikNIK not found in the data source.
200nameName not match to the full name registered in the datasource.
200birth_dateBirth date not match to the birth date registered in the datasource.
200selfie_photoSelfie not match with the face registered in the datasource.
200phonePhone conflict/already used to other NIK.
200emailEmail conflict/already used to other NIK.
200liveness_checkFace exist in photo but not alive.

Detail for Success and Verified Transaction

This case occurs if all parameters get successful results from the results of checking the data source (all valid data).

Request

Response

Remarks

{
  "nik": "VALID_NIK",
  "name": "VALID_NAME",
  "birth_date": "VALID_BIRTH_DATE",
  "email": "VALID_EMAIL",
  "phone": "VALID_PHONE",
  "selfie_photo": "base64 format",
  "ktp_photo": "base64 format",
  "reference_id": ""
}
{
   "message": "Certificate electronic verification has been done",
   "data": {
    "id": "8e31a91c-7437-4ed1-b086-06cbe247d6e7",
    "status": "verified",
    "reject_field": [],
    "reference_id": "ref_certel#e87c8bc2-5d10-455b-98a0-187d60f72873"
   }   
}

Successfull transaction

Detail for Success and Not Verified Transaction

This is a response that indicates there is an incorrect parameter after checking the data source. Below are also some examples of requests/responses.

NIK Not Verified

Request

Response

Remarks

{
  "nik": "VALID_NIK",
  "name": "VALID_NAME",
  "birth_date": "VALID_BIRTH_DATE",
  "email": "VALID_EMAIL",
  "phone": "VALID_PHONE",
  "selfie_photo": "base64 format",
  "ktp_photo": "base64 format",
  "reference_id": ""
}
{
   "message": "Certificate electronic verification has been done",
   "data": {
    "id": "8e31a91c-7437-4ed1-b086-06cbe247d6e7",
    "status": "not_verified",
    "reject_field": ["nik"],
    "reference_id": "ref_certel#e87c8bc2-5d10-455b-98a0-187d60f72873"
   }   
}

Success (not_verified)

Note: The transaction has been successfully checked against the data source and obtained some parameters with a value of 'false' which can be seen through the reject_field in the response

Name Not Verified

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"NAME_AS_ON_KT",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"channel":"VALID_CHANNEL",
"reference_id":””,
}
{
   "message": "Certificate electronic verification has been done",
   "data": {
    "id": "8e31a91c-7437-4ed1-b086-06cbe247d6e7",
    "status": "not_verified",
    "reject_field": ["name"],
    "reference_id": "ref_certel#e87c8bc2-5d10-455b-98a0-187d60f72873"
   }   
}

Success (not_verified)

Note: The transaction has been successfully checked against the data source and obtained some parameters with a value of 'false' which can be seen through the reject_field in the response

Birth Date Not Verified

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"BIRTH_DATE_AS_ON_KTP",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"channel":"VALID_CHANNEL",
"reference_id":””,
}
{
   "message": "Certificate electronic verification has been done",
   "data": {
    "id": "8e31a91c-7437-4ed1-b086-06cbe247d6e7",
    "status": "not_verified",
    "reject_field": ["birth_date"],
    "reference_id": "ref_certel#e87c8bc2-5d10-455b-98a0-187d60f72873"
   }   
}

Success (not_verified)

Note: The transaction has been successfully checked against the data source and obtained some parameters with a value of 'false' which can be seen through the reject_field in the response

Selfie Photo Not Verified

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"SELFIE_PHOTO”,
"ktp_photo":"base64 format”,
"channel":"VALID_CHANNEL",
"reference_id":””,
}
{
   "message": "Certificate electronic verification has been done",
   "data": {
    "id": "8e31a91c-7437-4ed1-b086-06cbe247d6e7",
    "status": "not_verified",
    "reject_field": ["selfie_photo"],
    "reference_id": "ref_certel#e87c8bc2-5d10-455b-98a0-187d60f72873"
   }   
}

Success (not_verified)

Note: The transaction has been successfully checked against the data source and obtained some parameters with a value of 'false' which can be seen through the reject_field in the response


Detail for Success and Verified with Reason Transaction

This case occurs where email, phone, or both have been correlated with a certain NIK, causing the status "verified_with_reason". If this case occurs, please contact Privy's customer support directly ([email protected]).

Conflict Email

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"CONFLICT_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"reference_id":””,
}

Success (verified_with_reason)

Note: It means that the email, phone number, or both have been used by another NIK (identification number), and the user is advised to contact Privy's customer service

Conflict Phone

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"CONFLICT_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"reference_id":””,
}

Success (verified_with_reason)

Note: It means that the email, phone number, or both have been used by another NIK (identification number), and the user is advised to contact Privy's customer service

Conflict Email and Phone

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"CONFLICT_EMAIL",
"phone":"CONFLICT_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"reference_id":””,
}

Success (verified_with_reason)

Note: It means that the email, phone number, or both have been used by another NIK (identification number), and the user is advised to contact Privy's customer service

Detail for Failed Transaction

Here are some examples of cases for validating the format of existing parameters. If validation fails, the transaction will receive a 400 response along with details such as:

  • error_code
  • error_fields
  • message

VALIDATION FORMAT NIK

NIK Digit Validation:

Request

Response

Remarks

{
"nik":"INVALID_FORMAT_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"reference_id":””,
}

Transaction error

Note: The transaction was not processed and received a code 400 due to a validation error

NIK Pattern Validation:

Request

Response

Remarks

{
"nik":"INVALID_PATTERN_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"reference_id":””,
}

Transaction error

Note: The transaction was not processed and received a code 400 due to a validation error.

Reason:

  1. NIK starts or ends with 0 (zero).
  2. NIK contains more than 4 consecutive number.
  3. The Date of Birth pattern in NIK does not align with the inputted NIK.

VALIDATION FORMAT BIRTH DATE

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"INVALID_FORMAT_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"reference_id":””,
}

Transaction error

Note: The transaction was not processed and received a code 400 due to a validation error

VALIDATION FORMAT SELFIE PHOTO

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"INVALID_FORMAT_SELFIE_PHOTO”,
"ktp_photo":"base64 format”,
"reference_id":””,
}

Transaction error

Note: The transaction was not processed and received a code 400 due to a validation error

VALIDATION FORMAT SELFIE PHOTO (NO FACE DETECTED)

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"INVALID_FORMAT_SELFIE_PHOTO_NO_FACE”,
"ktp_photo":"base64 format”,
"reference_id":””,
}

Transaction error

Note: The transaction was not processed and received a code 400 due to validation error

VALIDATION FORMAT KTP PHOTO

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"INVALID_FORMAT_KTP_PHOTO”,
"reference_id":””,
}

Transaction error

Note: The transaction was not processed and received a code 400 due to validation error

VALIDATION FORMAT EMAIL

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"INVALID_FORMAT_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"reference_id":””,
}

Transaction error

Note: The transaction was not processed and received a code 400 due to validation error

VALIDATION FORMAT PHONE

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"INVALID_FORMAT_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"reference_id":””,
}

Transaction error

Note: The transaction was not processed and received a code 400 due to validation error

Detail for Success Transaction but Liveness Check False/Failed

Request

Response

Remarks

{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"reference_id":””,
}

Success (not_verified)

Note: Failed because of liveness check, only liveness will be charged

Updated 1 day ago