Guidelines

API Request & Response

🎈Endpoint

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

🎈Headers

KeyTypeDescription
App-IDStringApplication ID that generated from Application Menu in Verihubs Client Dashboard.
To hit in Testing and Live mode you need a Production Application ID.
API-KeyStringAPI-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

ParameterTypeDescriptionExample
nikString16 digits of Nomor Induk Kependudukan as stated on the KTP.9171022512990011
nameStringFull name based on the KTP.John Doe
birth_dateStringBirth date in DD-MM-YYYY format based on the KTP.01-01-1901
emailStringEmail address that must be unique per NIK.[email protected]
phoneStringValid phone number, use country code but without plus (+) symbol. Must be unique per NIK.62812010101010101
selfie_photoStringSelfie photo in base64 format, minimum size 100KB, maximum size 4MB, and minimum pixel 480px (horizontal) X 640px (vertical). Please check Selfie & ID Card Best Practice check Selfie & ID Card Best Practice for details.Base64
ktp_photoStringKTP photo in base64 format, minimum size 100KB, maximum size 2MB, minimum pixel 480px (horizontal) X 360px (vertical). Please check Selfie & ID Card Best Practice for details.Base64
channelStringThis payload is currently not affecting any output due to inactivity of Electronic Certificate email notification.VERIHUBS
reference_idStringThis 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 youSERTEL_123

🎈Response

Response

HTTP CodeDescriptionResponse
200Successful Transaction; Transaction that is considered successful and has been successfully verified by the data source.{
"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"
}
}
400Invalid Payload; Transaction that is considered failed due to validation errors, an error_field will appear explaining the error.{
"message": "Invalid payload",
"error_code": "INVALID_PAYLOAD",
"error_fields": [
{
"field": "nik",
"message": "nik length should consist of 16 digit(s)"
}
]
}
401Authorization Failed; Transaction that unauthorized due to Application ID or API-Key issue. To hit in Testing and Live mode you need a Production Application ID and API-Key.{
"message": "Authorization Failed",
"error_code": "UNAUTHORIZED",
"error_fields": []
}
403Forbidden; The transaction is in Testing mode and not enough remaining quota. Please contact Verihubs Customer Support.{
"message": "Insufficient testing quota",
"error_code": "FORBIDDEN",
"error_fields": []
}
429Too Many Request; Spam Error as the transaction is read as spam, please wait a few seconds before re-performing the hit process.{
"message": "Too many request in the allowed time frame",
"error_code": "TOO_MANY_REQUEST",
"error_fields": []
}
500Internal Server Error; The transaction failed due to a server error that could be caused by data source constraints, timeout, internal error.{
"message": "Internal Server Error",
"error_code": "INTERNAL_SERVER_ERROR",
"error_fields": []
}

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 data source.
200nameFull name used to hit is not an exact match to full name registered in data source.
200birth_dateBirth date used to hit is not an exact match to birth date registered in data source.
200selfie_photoSelfie not match
200phonePhone conflict/already used to other NIK
200emailEmail conflict/already used to other NIK
200liveness_checkLiveness check false

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).

RequestResponseRemarks
{
"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"
}
}		Success (verified)

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.

Invalid NIK

RequestResponseRemarks
{
"nik":"INVALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"base64 format”,
"channel":"VALID_CHANNEL",
"reference_id":”transaction1”,
}		{
"message": "Certificate electronic verification has been done",
"data": {
"id": "22273b8b-f99c-48be-aeaf-ac5ef9402fea",
"status": "not_verified",
"reject_field": [
"nik"
],
"reference_id": "transaction1"
}
}		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

Invalid Name

RequestResponseRemarks
{
"nik":"VALID_NIK",
"name":"INVALID_NAME",
"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": "22273b8b-f99c-48be-aeaf-ac5ef9402fea",
"status": "not_verified",
"reject_field": [
"name"
],
"reference_id": "transaction1"
}
}		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

Invalid Birth Date

RequestResponseRemarks
{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"INVALID_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": "22273b8b-f99c-48be-aeaf-ac5ef9402fea",
"status": "not_verified",
"reject_field": [
"birth_date"
],
"reference_id": "transaction1"
}
}		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

Invalid Selfie Photo

RequestResponseRemarks
{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"INVALID_SELFIE_PHOTO”,
"ktp_photo":"base64 format”,
"channel":"VALID_CHANNEL",
"reference_id":””,
}		{
"message": "Certificate electronic verification has been done",
"data": {
"id": "22273b8b-f99c-48be-aeaf-ac5ef9402fea",
"status": "not_verified",
"reject_field": [
"selfie_photo"
],
"reference_id": "transaction1"
}
}		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

Invalid KTP Photo

RequestResponseRemarks
{
"nik":"VALID_NIK",
"name":"VALID_NAME",
"birth_date":"VALID_BIRTH_DATE",
"email":"VALID_EMAIL",
"phone":"VALID_PHONE",
"selfie_photo":"base64 format”,
"ktp_photo":"INVALID_KTP_PHOTO”,
"channel":"VALID_CHANNEL",
"reference_id":””,
}		{
"message": "Certificate electronic verification has been done",
"data": {
"id": "22273b8b-f99c-48be-aeaf-ac5ef9402fea",
"status": "not_verified",
"reject_field": [
"ktp_photo"
],
"reference_id": "transaction1"
}
}		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

RequestResponseRemarks
{
"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":””,
}		{
"message": "Certificate electronic verification has been done",
"data": {
"id": "7c5de075-739e-46c8-9aee-487696776c76",
"status": "verified_with_reason",
"reject_field": [
"email"
],
"reference_id": "ref_certel#dfb8b449-4d83-41e8-b2f4-0343ead765f4"
}
}		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

RequestResponseRemarks
{
"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":””,
}		{
"message": "Certificate electronic verification has been done",
"data": {
"id": "7c5de075-739e-46c8-9aee-487696776c76",
"status": "verified_with_reason",
"reject_field": [
"phone"
],
"reference_id": "ref_certel#dfb8b449-4d83-41e8-b2f4-0343ead765f4"
}
}		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

RequestResponseRemarks
{
"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":””,
}		{
"message": "Certificate electronic verification has been done",
"data": {
"id": "a9b2fd4a-780e-425c-a67b-a52d5febc2c2",
"status": "verified_with_reason",
"reject_field": [
"phone",
"email"
],
"reference_id": "ref_certel#3c42fa6b-c2c9-4705-8117-cf9d08c8d2aa"
}
}		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:

RequestResponseRemarks
{
"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":””,
}		{
"message": "Invalid payload",
"error_code": "INVALID_PAYLOAD",
"error_fields": [
{
"field": "nik",
"message": "nik length should consist of 16 digit(s)"
}
]
}		Transaction error

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

NIK Pattern Validation:

RequestResponseRemarks
{
"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":””,
}		{
"message": "Invalid payload",
"error_code": "INVALID_PAYLOAD",
"error_fields": [
{
"field": "nik",
"message": "Invalid nik"
}
]
}		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

RequestResponseRemarks
{
"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":””,
}		{
"message": "Invalid payload",
"error_code": "INVALID_PAYLOAD",
"error_fields": [
{
"field": "birth_date",
"message": "birth_date format is incorrect, should be DD-MM-YYYY"
}
]
}		Transaction error

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

VALIDATION FORMAT SELFIE PHOTO

RequestResponseRemarks
{
"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":””,
}		{
"message": "Invalid payload",
"error_code": "INVALID_PAYLOAD",
"error_fields": [
{
"field": "selfie_photo",
"message": "selfie_photo format is incorrect in body, should be in a valid base64 or URL format"
}
]
}		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)

RequestResponseRemarks
{
"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":””,
}		{
"message": "Invalid payload",
"error_code": "INVALID_PAYLOAD",
"error_fields": [
{
"field": "selfie_photo",
"message": "No face detected in image"
}
]
}		Transaction error

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

VALIDATION FORMAT KTP PHOTO

RequestResponseRemarks
{
"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":””,
}		{
"message": "Invalid payload",
"error_code"": "INVALID_PAYLOAD",
"error_fields": [
{
"field": "ktp_photo",
"message": "ktp_photo format is incorrect in body, should be in a valid base64 or URL format"
}
]
}		Transaction error

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

VALIDATION FORMAT EMAIL

RequestResponseRemarks
{
"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":””,
}		{
"message": "Invalid payload",
"error_code": "INVALID_PAYLOAD",
"error_fields": [
{
"field": "email",
"message": "email must be email format"
}
]
}		Transaction error

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

VALIDATION FORMAT PHONE

RequestResponseRemarks
{
"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":””,
}		{
"message": "Invalid payload",
"error_code": "INVALID_PAYLOAD",
"error_fields": [
{
"field": "phone",
"message": "phone must be numeric"
}
]
}		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

RequestResponseRemarks
{
"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": "a9b2fd4a-780e-425c-a67b-a52d5febc2c2",
"status": "not_verified",
"reject_field": [
"liveness_check”
],
"reference_id": "ref_certel#3c42fa6b-c2c9-4705-8117-cf9d08c8d2aa"
}
}		Success (not_verified)

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

Updated 2 months ago