Async API

This API initiates the verification process asynchronously and returns eventId for which the status can be checked later.

Identity verification async API can be enabled on the requirement, please contact the VIDA support team to enable it.

API Description

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

Headers

Name	Type	Value
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 as per family card (KK/Kartu Keluarga)
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 Response

Verification Request Created

Asynchronous Identity Verification request is created and eventId is returned to get the verification request details.

HTTP Status Code: 200

JSON Response

{
    "data": {
        "eventId": "99a173f7-b1fd-4495-8787-59940b9a1efc"
    }
}

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

{
    "data": {
        "eventId": "99a173f7-b1fd-4495-8787-59940b9a1efc"
    }
}

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 - 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": "Invalid phone number",
            "detail": "mobile"
        }
    ]
}

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

Get Verification Status and Verification Data

You can obtain the transaction status and details through a separate API call after the request has been processed.

To get the verification status please follow the Verification Status API and to get verification data please follow the Verification Data API.