Sync API

The Identity Verification API is a service provided by VIDA that allows partners to confirm the identity of their users. This is done by sending the user's details, such as their name, dob, and govt ID numbers, along with the user informations that need to be verified in a request to the API. When the API is invoked, it performs a set of checks and validations on the provided information to verify the user's identity. The checks and validations may include comparing the provided information against a set of official government records, checking for any discrepancies or inconsistencies, and performing a facial recognition analysis to compare the user's photo with their ID photo.

Once the verification process is complete, the API returns a unique transaction ID (eventId) which can be used to track the status of the verification process. The API also sends a response indicating the outcome of the verification, such as approval or rejection, along with any additional information or feedback that may be relevant. The API can be integrated with the partner's platform or application, allowing them to perform identity verification as part of their own user registration or onboarding process. This eliminates the need for users to visit a separate website or portal to verify their identity. Additionally, the API also support webhook, which can be configured to notify partners of the status of the verification process and any updates in real-time.

API Description

POST https://services-sandbox.vida.id/main/v3/services/kyc

Headers

Name	Type	Description
Authorization*		OAuth access token. Get the token by calling the Get Access Token API
Content-Type*	application/json	Format type of request body

Request Body for Main Parameters

Name	Type	Description
mobile*	String	User mobile number with country code without space. 1. [+] [country code] [ user phone number] 2. No special characters. 3. Provide phone number in E.164 format. example: [phone]
email	String	User valid email address example: [e-mail]
govId*	String	(Government Id - User NIK number) 16 digit number of Nomor Induk Kependudukan (Government Issued Id- NIK)
fullName*	String	User full name as per KTP. example: Johnny Rudiantara Sembiring
dob*	String	user date of birth as per KTP. Provide user date of birth In YYYY-MM-DD format. example: 1975-08-16
selfiePhoto*	String	Format: base64 string Provide the user selfie for whom face recognition should be performed. The image is also sent for face-match checks. Face-match check: Verifying the user selfie with authoritative source record image.
consent*	Object	"consent": { "consentedAt": "1614089870", "consentGiven": true }
ConsentGiven*	Boolean	Consent provided by the partner to record and verify the user details. Possible values: True, False
ConsentedAt*	String	This value represents the time at which the user consented to do their identity verification. The value is Epoch time in seconds
partnerTrxId	String	Reference ID supplied by the customer, used for identifying the transaction and it can't be duplicated.

Request Body for Extended Parameters

Name	Type	Description
motherMaidenName	String	User mother’s maiden name as per KTP.
familyCardNo	String	User's family card number (if idCardType is KTP)
pob	String	User's place of birth as per KTP.
address	String	User residential address as per KTP
village	String	User residential village as per KTP
district	String	User residential district as per KTP
city	String	User residential city as per KTP
province	String	User residential province as per KTP

API Sample Request

Sample Request

{
    "partnerTrxId": "8705-29ca45b0ef32",
    "mobile": "[phone]",
    "govId": "3511000101806300",
    "govIdType": "KTP",
    "fullName": "Userbcde", 
    "dob": "1989-01-01",
    "selfiePhoto": "/9j/4AAQSkZJRgAB...",
    "consent": {
        "consentedAt": "1614089870",
        "consentGiven": true
    }
}

API Responses

Verification Successful

The demographic verification, liveness verification, and face-match verification are successful for the provided user details.

The e-certificate will be successfully issued if the following conditions are met:

• The user demographic information is match with authoritative source.

• The user selfie photo information is match with authoritative source.

• The user selfie photo liveness score is equal to or less than its threshold score.

EventId: When an identity verification request is received by VIDA, the VIDA system auto-generates a reference id that is also known as eventId. It is a unique id per request and that can be used to track the identity verification status and transaction details.

HTTP Status Code: 200

JSON Response

{
	"data": {
		"eventId": "1000073-c00f-4008-8005-29000000000f32",
		"fields": [
			{
				"score": 0.01113,
				"field": "liveness"
			}

		],
		"certificateIssued": 200
	}
}

Demographic Parameter Mismatch

The demographic parameters is not match with Authoritative source.

Recommendation: The partner must check all the demographic parameters before sending it.

Information: If any of the provided demographic did not match with the authoritative source data, the demographic verification will fail. Therefore, the identity verification status will also be “False.”

HTTP Status Code: 200

JSON Response

{
	"data": {
		"eventId": "1000073-c00f-4008-8005-29000000000f32",
		"fields": [{
				"score": 0.01113,
				"field": "liveness"
			}

		],
		"certificateIssued": 444
	}
}

Selfie Mismatch

selfiePhoto does not match with the authoritative source.

Recommendation: The partner must send a correct selfie photo of the user.

HTTP Status Code: 200

JSON Response

{
	"data": {
		"eventId": "1000073-c00f-4008-8005-29000000000f32",
		"fields": [
			{
				"score": 0.01113,
				"field": "liveness"
			}

		],
		"certificateIssued": 444
	}
}

Selfie - Not Live

The selfie is not a live image.

Recommendation: The partner must check that the provided selfie is a live image and not a hacked image.

HTTP Status Code: 200

JSON Response

{
    "data": {
        "eventId": "be22451d-56a5-4798-ae01-afa2efcf7847",
        "fields": [
            {
                "score": 0.97,
                "field": "liveness"
            }
        ],
        "certificateIssued": 444
    }
}

Face Occluded/Missing in Selfie

There is no face in the selfie image/face is occluded.

Recommendation: The partner must check that the selfie should contain the user's face.

HTTP Status Code: 200

JSON Response

{
    "data": {
        "eventId": "5ec9b091-9142-4e21-88dc-0777f706fa67",
        "fields": [
            {
                "score": -100.0,
                "field": "liveness"
            }
        ],
        "certificateIssued": 444
    }
}

Certificate Issuance Failed

Certificate issuance has failed. The certificateIssued parameter in the response will have 443

HTTP Status Code: 200

JSON Response

{
    "data": {
        "eventId": "be22451d-56a5-4798-ae01-afa2efcf7847",
        "fields": [
            {
                "score": 0.97,
                "field": "liveness"
            }
        ],
        "certificateIssued": 443
    }
}

UnAuthorised - Invalid Credentials

The client secret key parameter or its value is either missing or incorrect. The partner must check the client's secret key before sending the request.

HTTP Status Code: 401

JSON Response

{
    "errors": [
        {
            "code": 1006,
            "title": "Missing required parameter",
            "detail": "Incorrect values found in request body"
        }
    ]
}

Bad Request - Missing Required Parameter

The input request body is not well formatted.

Recommendation:

The partner must check that the API request body is well-formatted before sending the request

HTTP Status Code: 400

JSON Response

{
    "errors": [
        {
            "code": 1006,
            "title": "Missing required parameter",
            "detail": "Incorrect values found in request body"
        }
    ]
}

Bad Request - Invalid GovID

The input format for GovID (NI) is invalid.

Recommendation:

The partner must check that the GovID (NIK) must be 16 digits of a number.

HTTP Status Code: 400

JSON Response

{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid GovID entered, must be 16 digit",
            "detail": "govId"
        }
    ]
}

Bad Request - Request Parameter Not Allowed

When a partner tries to send a parameter in the request that is not configured, a similar error message will appear.

Example: Here, Place of birth (pob) parameter is not configured for the partner.

HTTP Status Code: 400

JSON Response

{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid request data",
            "detail": "Field(s) pob not allowed"
        }
    ]
}

Bad Request - Invalid Request Parameter

The phone number parameter value is either missing or in an incorrect format in the API request body.

Recommendation: The partner must send a valid mobile parameter and its value in the API request body. To know more, see the parameter required format in the request body table.

HTTP Status Code: 400

JSON Response

{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid phone number",
            "detail": "mobile"
        }
    ]
}

Bad Request - Mandatory Request Parameter Missing

The Mandatory parameter is missing in the request body.

Recommendation : The partner must send all the mandatory details in the request along with other required details

HTTP Status Code: 400

Example : The govId (NIK) is a mandatory field. The partner must send the user govId (NIK) details in the request along with other required details

JSON Response

{
    "errors": [
        {
            "code": 1006,
            "title": "must not be blank",
            "detail": "govId"
        }
    ]
}

Bad Request - Invalid Base64 String

The base64 string of the user selfie is not valid in the API request.

Recommendation: The partner must check the user selfie base64 string value before sending the request.

HTTP Status Code: 400

JSON Response

{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid image base64 String",
            "detail": "selfiePhoto"
        }
    ]
}

Bad Request - Invalid Format

Date of birth request body parameter value is in incorrect format.

Recommendation: The partner must send the date of birth in the required format as mentioned in the request body.

HTTP Status Code: 400

JSON Response

{
    "errors": [
        {
            "code": 1006,
            "title": "Missing required parameter",
            "detail": "Incorrect Date value"
        }
    ]
}

Bad Request - One or More Mandatory Parameters Missing

One or more required parameters are missing. The configuration mandates to send all the mandatory parameters in the request.

Recommendation: The partner must send all the mandatory parameters in the request body.

HTTP Status Code: 400

JSON Response

{
    "errors": [
        {
            "code": 1006,
            "title": "Invalid request data",
            "detail": "All of the fields email,dob,fullName,mobile,selfiePhoto,address,familyCardNo,motherMaidenName,village,district,city,province should be provided"
        }
    ]
}

URL Not Found

The API endpoint URL is not valid.

Recommendation: The partner must send a valid endpoint URL.

HTTP Status Code: 404

JSON Response

{
    "timestamp": "2022-11-07T10:43:44.429+00:00",
    "status": 404,
    "error": "Not Found",
    "message": "",
    "path": "/services/kyc"
}

Internal Server Error

An internal server occurred, please try after some time.

Recommendation: The partner should send the API request after some time.

HTTP Status Code: 500

JSON Response

{
    "errors": [
        {
            "code": 1000,
            "title": "Verification failed",
            "detail": "An internal error occurred. Please try again"
        }
    ]
}