Guidelines

API Request & Response

Endpoint

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

Headers

KeyTypeDescription
App-IDString
  • 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-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

ParameterTypeDescriptionValidationExample
nikStringNomor 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
nameStringFull name as stated on the KTP.
  • Alphabet [a-z][A-Z]
  • Dot (.)
  • Comma (,)
  • Single quote (')
  • Slash (/)
  • Dash (-)
  • John Doe
  • John Doe, S.E.
birth_dateStringBirth 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
emailStringEmail address that must be unique per NIK.
  • Must be email format (@)
  • Must be unique per NIK for Certificate Electronic generation.
[email protected]
phoneStringPhone number that must be unique per NIK.
  • Use country code
  • Must be a valid phone number
6281277863450
selfie_photoStringThe 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_photoStringA full pyshical/digital KTP photo
  • Format base64
  • Minimum size 100 KB
  • Maximum size 2 MB
  • Minimum pixel 480 x 360 px
Base64
reference_idStringA 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 CodeDescription
200Successful 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
401Authorization Failed; Possible reason:
  • Sandbox App ID and/or API Key used in Production mode transaction.
  • Unmatch App ID and API Key.
403Forbidden; The transaction is in Testing mode and not enough remaining quota. Possible reason:
  • Electronic Certificate quota
  • Liveness-Sertel quota
429Too 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).

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"
   }   
}
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

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": "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

RequestResponseRemarks
{
"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

RequestResponseRemarks
{
"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

RequestResponseRemarks
{
"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

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": "8e31a91c-7437-4ed1-b086-06cbe247d6e7",
    "status": "verified_with_reason",
    "reject_field": ["email"],
    "reference_id": "ref_certel#e87c8bc2-5d10-455b-98a0-187d60f72873"
   }   
}
  • Email has been used by another NIK.

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": "8e31a91c-7437-4ed1-b086-06cbe247d6e7",
    "status": "verified_with_reason",
    "reject_field": ["email"],
    "reference_id": "ref_certel#e87c8bc2-5d10-455b-98a0-187d60f72873"
   }   
}
  • Phone has been used by another NIK

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": "8e31a91c-7437-4ed1-b086-06cbe247d6e7",
    "status": "verified_with_reason",
    "reject_field": ["email","phone"],
    "reference_id": "ref_certel#e87c8bc2-5d10-455b-98a0-187d60f72873"
   }   
}
  • Phone and email has been used by another NIK

Detail for Failed Transaction

Failed transaction has two main reasons:

  1. Parameter validation
  2. Error in datasource.

Parameter Validation

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":””,
}
{
    "error_code": "INVALID_PAYLOAD",
    "error_fields": [
        {
            "field": "nik",
            "message": "nik length should consist of 16 digit(s)"
        }
    ],
    "message": "Invalid payload"
}
  • HTTP 400
  • NIK is not exact 16 digits.

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":””,
}
{
    "error_code": "INVALID_PAYLOAD",
    "error_fields": [
        {
            "field": "nik",
            "message": "nik value is invalid"
        }
    ],
    "message": "Invalid payload"
}
  • HTTP 400
  • NIK start from 0
  • NIK has 5 consecutive digits (ex: 12345)

Birth Date Validation

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":””,
}

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":””,
}

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":””,
}

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":””,
}

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":””,
}

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":””,
}

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":””,
}

Success (not_verified)

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