Biometric & Demographic Verification

This API allows partners to perform both biometric and demographic verification in a single request. By submitting user information and a captured selfie, the API validates identity through facial analysis, liveness detection, and demographic cross-checks against trusted data sources. This combined flow enables efficient, high-assurance verification while minimizing user friction. The following section outlines the required request parameters for initiating this verification process.

Parameters

Main Parameters

Field	Type	Description	Sample Value
partnerTrxId*	string	Generate a unique transaction ID in UUID format and include it in the request to link your transaction with the VIDA transaction.	Generated random UUID by the partner. Example: 1000073-c00f-4008-8005-d2ec4d9be956
transactionType*	string	Type of the transaction	In the biometric and demographic verification below transaction type is applicable: FULL_FRAUD_ASSESSMENT
govId*	string	The user's government ID number (NIK number)	NIK - Nomor Induk Kependudukan), consisting of a 16-digit number: 3451222123456716
govIdType	string	The type of IDCard Document.	Supported values: "KTP"
fullName*	string	Users Full Name which should same with registered ID	User full name as per KTP. Example: Johnny Rudiantara Sembiring
dob*	string	User's Date of Birth	Date of Birth in yyyy-mm-dd format Example: 1989-01-01
mobile*	string	The user's verified mobile number with the country code, provided in E.164 format without spaces or special characters.	If the mobile number isn’t available, a verified email address can be passed, however, one of the two is mandatory. Example: [phone]
email	string	The user's valid email address	Example: [e-mail]
consent*	object	A user’s consented timestamp value where they agreed to consent sharing data with VIDA	"consent": { "consentedAt": "1614089870", "consentGiven": true }
selfiePhoto*	base64-encoded string	A plain base64-encoded string of the user's selfie for facial recognition and face-match checks, adhering to specified image standards.	Example: "/9j/4AAQSkZJRgABAQAAJAAkAAD/4QhcR..."
idCardPhoto	base64-encoded string	A plain base64-encoded string of the user ID card Photo (i.e. KTP)	Example: "/9j/4AAQSkZJRgABAQAAJAAkAAD/4QhcR..."

*required parameter

Extended Demographic Parameters

Extended demographic parameters refer to additional identity-related fields that go beyond the standard personal information typically used in identity verification. Including extended parameters can enhance the accuracy of verification, support higher assurance levels, or fulfill regulatory and business requirements for more detailed profiling.

Field	Type	Description	Sample Value
pob	string	User's Place of Birth	Jakarta
motherMaidenName	string	The user's mother’s maiden name as per IDCard.	Siti Elizabeth
maritalStatus	string	The user's marital status as per IDCard.	Belum Kawin
familyCardNo	string	The user's family card number (if idCardType is KTP)	3451222123456716
address	string	The user's residential address as per KTP (Alamat).	Jl. Pasti Cepat A7/66
village	string	The user's residential village as per KTP (Kelurahan/Desa).	Pegadungan
villageCode	string (4 digit)	The user's residential village code (Kelurahan/Desa).	1001
district	string	The user's residential district as per KTP (Kecamatan).	Kalideres
districtCode	string (2 digit)	The user's residential district code (Kecamatan).	10
city	string	The user's city of residence as per KTP (Kabupaten/Kota)	Jakarta Barat
cityCode	string (2 digit)	The user's city code of residence (Kabupaten/Kota)	13
province	string	The user's province of residence as per KTP (Provinsi).	DKI Jakarta
provinceCode	string (2 digit)	The user's province code of residence (Provinsi).	23

Alternative: Multistage Full Verification with VIDA

VIDA supports Biometric and Demographic Verification executed separately.

This flow is suitable for use case where:

• Partners who requires demographic check first, before collecting user selfie photo

• Partner do intermediary check in between Demographic check and Biometric checks. For example: Credit scoring check

Such flow enable a more flexible verification flow where the client needs to handle both stages separately but link them through a shared transaction reference called groupId

1. During the Step 1: Demographic-only Verification, partners should send a unique groupId that can be used to track related transactions and pair it with biometric verification for later.

   1. The same groupId should be sent during the Step 2: Biometric-only Verification to allow for NIK linking between two separate checks.

      1. In step 2, VIDA will check the Step 1's Demographic verification result based on groupId, which will determine the certificate issuance status

   2. groupId will expire within 1 day, and will be valid for up to 3 times of Biometric Verification retries

2. Each step will return a response transactionId that are unique for either calls

   1. A registrationId is returned upon successful Step 2. This unique ID signifies the user, which can be used for digital signature for VIDA DirectSign API.

Using this flow — where both Demographic and Biometric Verification are done through VIDA — then a Level 2 Certificate will be issued when both checks are accepted.

For API specification of Multistage Verification approach, please visit the Demographic-only Verification and Biometric-only Verification page

Sample Request

Sample Request (Main Parameters Only)

{
    "partnerTrxId": "{{random-UUID}}", //must be unique for every transaction.
    "transactionType":"FULL_FRAUD_ASSESSMENT",
    "mobile":"Phone Number",
    "email": "[e-mail]",
    "govId": "Gov Id from ID Card",
    "govIdType": "KTP",
    "fullName": "Name from ID Card", 
    "dob": "YYYY-MM-DD",
    "idCardPhoto":"{{KTPCARD}}",
    "selfiePhoto":"{{selfieID1}}",
    "consent": {
        "consentedAt": "1614089870",
        "consentGiven": true
    }
}

Sample Request (With Extended Demog)

{
  // MANDATORY FIELDS
  "partnerTrxId": "{{random-UUID}}", //must be unique for every transaction.
  "transactionType": "DATA_FRAUD_ASSESSMENT",
  "govId": "{{GOV_ID}}",
  "govIdType": "KTP",
  "fullName": "{{FULL_NAME}}",
  "mobile": "{{MOBILE_E164}}",
  "email": "{{EMAIL}}",
  "dob": "{{DOB_YYYY_MM_DD}}",
  "selfiePhoto": "{{SELFIE_BASE64}}",
  "consent": { "consentedAt": {{UNIX_EPOCH_SECONDS}}, "consentGiven": true },
  
  //Extended Demographic Fields
  "address": "{{ADDRESS}}",
  "district": "{{DISTRICT_NAME}}",
  "districtCode": "{{DISTRICT_CODE}}",
  "village": "{{VILLAGE_NAME}}",
  "villageCode": "{{VILLAGE_CODE}}",
  "city": "{{CITY_NAME}}",
  "cityCode": "{{CITY_CODE}}",
  "province": "{{PROVINCE_NAME}}",
  "provinceCode": "{{PROVINCE_CODE}}",
  "familyCardNo": "{{FAMILY_CARD_NO}}",
  "maritalStatus": "{{MARITAL_STATUS}}",
  "gender": "{{GENDER}}",
  "occupation": "{{OCCUPATION}}",
  "motherMaidenName": "{{MOTHER_MAIDEN_NAME}}",
  "pob": "{{PLACE_OF_BIRTH}}"
}

Sample Response

HTTP Status Code: 200

JSON Response

{
    "data": {
        "authenticationLevel": "IAL2",
        "certificate": {
            "level": 2,
            "detail": "Certificate with long term validity is issued and its utilization is for digital signature and digital identity purpose in VIDA system."
        },
        //authenticationLevel & certificate field should NOT be used programmatically
        //authenticationLevel & certificate result depends on verification data availability & its RA level
        //Instead, customer should define successful transaction based on Status Check API, score & fraudAssessment status,

        "transactionType": "FULL_FRAUD_ASSESSMENT",
        "transactionId": "713ec63c-fa89-4efc-971b-d1120112eef9",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 1.0
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            },
            {
                "name": "selfiePhoto",
                "result": 0.9
            },
            {
                "name": "liveness",
                "result": 0.164398
            },
            {
                "name": "imgManipulationScore",
                "result": 0.117981
            }
        ]
    }
}

Sample Response Value Explanation

Values	Description
full_name	Degree of match between the provided full name and stored data.
selfiePhoto	The degree of match between the selfie provided and the stored biometric data. (Score threshold: 0 to 1)
liveness	Score indicating the likelihood that the selfie represents a live person. (Score: 0 to 1)
imgManipulationScore	Score that indicate the probability of image manipulation in the selfie. (Score: 0 to 1)
dob	Score that indicate the probability of date of birth data validation. (Score: 0 to 1)
fraudAssessment	Indicates the current state of the fraud assessment process. Status: SUBMITTED — The assessment has been submitted and is pending review. At this stage, the data will be processed through post-correction. Status: COMPLETED — The review process is finished, and the result is either approved or rejected: Approved: The data has been successfully corrected and validated. Rejected: The data was found to be incorrect or spoofed, and has been rejected.
authenticationLevel	Assurance level of the authentication process. authenticationLevel field should not be used programmatically to determine a successful transaction. Instead, customer should define successful transaction based on Status Check API, score & fraudAssessment status
certificate	Details regarding the certificate's trustworthiness for digital signatures. certificate field should not be used programmatically to determine a successful transaction. Instead, customer should define successful transaction based on Status Check API, score & fraudAssessment statu

1. Accept Responses

HTTP Status Code: 200

Status : SUCCESS

Main Required Parameters

JSON Response

{
    "data": {
        "authenticationLevel": "IAL2",
        "certificate": {
            "level": 2,
            "detail": "Certificate with long term validity is issued and its utilization is for digital signature and digital identity purpose in VIDA system."
        },
        //authenticationLevel & certificate field should NOT be used programmatically
        //authenticationLevel & certificate result depends on verification data availability & its RA level
        //Instead, customer should define successful transaction based on Status Check API, score & fraudAssessment status,

        "transactionType": "FULL_FRAUD_ASSESSMENT",
        "transactionId": "unique transaction id generated to identify this transaction",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 1.0
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            },
            {
                "name": "selfiePhoto",
                "result": 0.9
            },
            {
                "name": "liveness",
                "result": 0.164398
            },
            {
                "name": "imgManipulationScore",
                "result": 0.117981
            }
        ]
    }
}

With All Extended Demographic Parameters

JSON Response

{
    "data": {
        "authenticationLevel": "IAL2",
        "certificate": {
            "level": 2,
            "detail": "Certificate with long term validity is issued and its utilization is for digital signature and digital identity purpose in VIDA system."
        },
        //authenticationLevel & certificate field should NOT be used programmatically
        //authenticationLevel & certificate result depends on verification data availability & its RA level
        //Instead, customer should define successful transaction based on Status Check API, score & fraudAssessment status,

        "transactionType": "FULL_FRAUD_ASSESSMENT",
        "transactionId": "unique transaction id generated to identify this transaction",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 1.0
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "mother_maiden_name",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            },
            {
                "name": "selfiePhoto",
                "result": 0.9
            },
            {
                "name": "liveness",
                "result": 0.164398
            },
            {
                "name": "imgManipulationScore",
                "result": 0.117981
            }
        ]
    }
}

2. Reject Responses

2.1 Below threshold

Case when selfie photo or demographic check result is below the VIDA assurance threshold.

HTTP Status Code: 200

Status : Success

SelfiePhoto Score

JSON Response

{
    "data": {
        "transactionType": "FULL_FRAUD_ASSESSMENT",
        "transactionId": "2c08afcc-fbb5-4409-8d2e-28bd6f2cddbe",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 1.0
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "mother_maiden_name",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            },
            {
                "name": "selfiePhoto",
                "result": 0.30000000000000004
            },
            {
                "name": "liveness",
                "result": 0.070489
            },
            {
                "name": "imgManipulationScore",
                "result": 0.081049
            }
        ]
    }
}    

Demographic Score

JSON Response

{
    "data": {
        "transactionType": "FULL_FRAUD_ASSESSMENT",
        "transactionId": "38f32f36-ebb9-4a72-94ad-554321e9027d",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 0.375
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            },
            {
                "name": "selfiePhoto",
                "result": 0.9
            },
            {
                "name": "liveness",
                "result": 0.070489
            },
            {
                "name": "imgManipulationScore",
                "result": 0.081049
            }
        ]
    }
}

Demographic & SelfiePhoto Score

JSON Response

{
    "data": {
        "transactionType": "FULL_FRAUD_ASSESSMENT",
        "transactionId": "8d069f89-c917-4c9e-8292-fe2cbfe7b487",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 0.375
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            },
            {
                "name": "selfiePhoto",
                "result": 0.30000000000000004
            },
            {
                "name": "liveness",
                "result": 0.070489
            },
            {
                "name": "imgManipulationScore",
                "result": 0.081049
            }
        ]
    }
}

2.2 Liveness and Image Manipulation not passed

HTTP Status Code: 200

Status : Success

JSON Response

Liveness Check Error & Image Manipulation Check Failed

{
    "data": {
        "transactionType": "FULL_FRAUD_ASSESSMENT",
        "transactionId": "320814b5-b97c-46a9-8c3b-96e844e88c84",
        "fraudAssessment": "COMPLETED",
        "assessmentResults": [
            {
                "name": "liveness",
                "result": 0.999932
            },
            {
                "name": "imgManipulationScore",
                "result": 0.997597
            }
        ]
    }
}

2.3 Image quality not passed (single detail)

HTTP Status Code: 200

Status : SUCCESS

Face Too Small

JSON Response

{
    "transactionId": "2ad38778-00d9-4fdf-b509-a3b6bf35eb34",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1052,
            "title": "Detect Un-standardized Image Quality",
            "detail": "Face too small"
        }
    ]
}

Face Occluded

JSON Response

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1051,
            "title": "Detect Un-standardized Image Quality",
            "detail": "Face Occluded"
        }
    ]
}

Multiple Faces Detected

JSON Response

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1055,
            "title": "Detect Un-standardized Image Quality",
            "detail": "No face detected"
        }
    ]
}

Image is Blurry

JSON Response

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        }
    ]
}

Underexposure

JSON Response

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "errors": [
        {
            "code": 1074,
            "title": "Image Quality Is Below Threshold",
            "detail": "Under Exposure"
        }
    ]
}

Overexposure

JSON Response

{
    "transactionId": "2ad38778-00d9-4fdf-b509-a3b6bf35eb34",
    "errors": [
        {
            "code": 1075,
            "title": "Image Quality Is Below Threshold",
            "detail": "Over Exposure"
        }
    ]
}

Unnatural Color

JSON Response

{
    "transactionId": "b0f4a52f-d917-41d1-8e0b-23fa93c34d15",
    "errors": [
        {
            "code": 1063,
            "title": "Image Quality Is Below Threshold",
            "detail": "UnNatural Color"
        }
    ]
}

2.4 Image quality not passed (multiple details)

HTTP Status Code: 200

Status : Success

Blur and Overexposure

JSON Response

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1075,
            "title": "Image Quality Is Below Threshold",
            "detail": "Over Exposure"
        },
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        }
    ]
}

Blur and Underexposure

JSON Response

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1074,
            "title": "Image Quality Is Below Threshold",
            "detail": "Under Exposure"
        },
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        }
    ]
}

Blur and Unnatural Color

JSON Response

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "groupId": "{{as received in request}}",
    "errors": [
        {
            "code": 1063,
            "title": "Image Quality Is Below Threshold",
            "detail": "UnNatural Color"
        },
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        }
    ]
}

Unnatural Color and Overexposure

JSON Response

{
    "transactionId": "b8cc863f-d61e-4f62-b2a0-63796903798f",
    "errors": [
        {
            "code": 1075,
            "title": "Image Quality Is Below Threshold",
            "detail": "Over Exposure"
        },
        {
            "code": 1063,
            "title": "Image Quality Is Below Threshold",
            "detail": "UnNatural Color"
        }
    ]
}

3. Error Responses

These errors occur when one or more mandatory fields are not provided in the request. The response includes details of the missing parameter in the detail field.

HTTP Status Code: 400

Status : ERROR

Missing (fullName)

JSON Response

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

Missing (selfiePhoto)

JSON Response

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

Missing (DOB and fullName)

JSON Response

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

4. Response when the API submitted in Manual Review

Response returned when the API submission enters the manual review stage.

HTTP Status Code: 440

Status: SUBMITTED

JSON Response for Manual Review

{
    "data": {
        "transactionType": "FULL_FRAUD_ASSESSMENT",
        "transactionId": "82a2b8d8-3078-470a-86a2-a7d54f23ab7f",
        "fraudAssessment": "SUBMITTED",
        "assessmentResults": [
            {
                "name": "full_name",
                "result": 0.6150000000000001
            },
            {
                "name": "dob",
                "result": 1.0
            },
            {
                "name": "nik",
                "result": 1.0
            },
            {
                "name": "selfiePhoto",
                "result": 0.9
            }
        ]
    }