API Reference

To initiate Biometric Verification using the VIDA Verify API, users must include both imageFaceMatchVerification and imageLivenessVerification in their list of operations and provide the required data for each process.

The API is designed to execute both operations concurrently. However, the outcome of Image Face Match Verification is directly dependent on the result of Image Liveness Verification. If the Image Liveness Verification fails—indicating the absence of a live person—there will be no response returned for the Image Face Match Verification. This ensures that facial matching is only performed when the authenticity of a live presence has been validated.

The overall success or failure of the Biometric Verification is, therefore, contingent upon passing the Image Liveness Verification. This layered verification process reinforces security by preventing unauthorized or spoofed attempts during identity authentication.

Additionally, this API can also perform Blacklist Check, given this service is enabled upon request.

Performing Liveness Check

For details liveness check please refer to here

API Description

POST https://{vida-host}/api/v1/verify

Headers

Name	Type	Description
Authentication*	String	Bearer <Token>
Content-Type		Format type of request body

Request Body

Name	Type	Description
operations*	String	["imageLivenessVerification"]
payload*	String	{ "partnerTrxId": "random-uuid","groupId": "random-uuid",""faceImage": "Base64 encoded image" }
userConsent*	String	{ "userIP": "0.0.0.0", "country": "MYS", "obtained": true, "obtainedAt": "1680700959" }

Sample Request and Response

Request

{
    "operations": ["imageLivenessVerification"],
    "payload": {
        "partnerTrxId": "{{$guid}}",
        "groupId": "{{$guid}}",
        "faceImage": ""
    },
    "userConsent": {
        "userIp": "226.80.211.232",
        "country": "MYS",
        "obtained": true,
        "obtainedAt": "1680700959"
    }
}

Response

{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
​
    "imageLivenessVerificationResult": {
        "data": {
            "code": 1043,
            "message": "Selfie photo is a live photo",
            "score": 0.066661
        }
    }
}

Performing Biometric Verification

API Description

POST https://{vida-host}/api/v1/verify

Headers

Name	Type	Description
Authentication*	String	Bearer <Token>
Content-Type		Format type of request body

Request Body

Name	Type	Description
operations*	String	["imageFaceMatchVerification","imageLivenessVerification"]
payload*	String	{ "partnerTrxId": "random-uuid","groupId": "random-uuid",""faceImage": "Base64 encoded image","croppedFaceImage"or"idFrontSideImage": "Encoded Base64 id card" } Sample Request​
userConsent*	String	{ "userIP": "0.0.0.0", "country": "MYS", "obtained": true, "obtainedAt": "1680700959" }

Sample Request and Response

Request

{
  "operations": [
    "imageFaceMatchVerification",
    "imageLivenessVerification"
  ],
  "payload": {
    "partnerTrxId": "random-uuid",
    "groupId": "random-uuid",
    "faceImage": "Base64 encoded image",
    "idFrontSideImage": "Encoded Base64 Id card"
  },
  "userConsent": {
    "userIP": "0.0.0.0",
    "country": "MYS",
    "obtained": true,
    "obtainedAt": "1680700959"
  }
}

Response

HTTP Status Code: 200

{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
​
   "imageFaceMatchVerificationResult": {
        "data": {
            "code": 1042,
            "message": "Selfie photo matches with reference photo",
            "score": 0.992796
        }
    },
    "imageLivenessVerificationResult": {
        "data": {
            "code": 1043,
            "message": "Selfie photo is a live photo",
            "score": 0.066661
        }
    }
}

Performing Blacklist Check

Purpose

To prevent onboarding or verification of users whose facial images appear in a blacklist database. The check runs before the faceMatch operation, and if a match is found, the faceMatch step will be skipped. Blacklist Check can be done as part of Liveness Check and also standalone Blacklist Check.

Flow

1. Check if Blacklist Check is enabled for product, if yes then perform this check

2. If the blacklist check fails (face found in blacklist), the system will return an error response with appropriate code and message.

3. If there is no blacklist image found, the system will return the success response.

API Description

POST https://{vida-host}/api/v1/verify

HTTP Status Code : 200

Success JSON Response for Face Match with No Blacklist Found

{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
​
   "imageFaceMatchVerificationResult": {
        "data": {
            "code": 1042,
            "message": "Selfie photo matches with reference photo",
            "score": 0.992796
        }
    },
    "imageLivenessVerificationResult": {
        "data": {
            "code": 1043,
            "message": "Selfie photo is a live photo",
            "score": 0.066661
        }
    },
    "blacklistCheckResult": {
        "faceReferences": []
    }
}

Success JSON Response for Face Match With Blacklist Warning

{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
​    "warnings": [
        {
            "message": "Image is blacklisted.",
            "code": 10501,
            "operations": [
                "imageFaceMatchVerification"
            ]
        }
    ],
   "imageFaceMatchVerificationResult": {
        "data": {
            "code": 1042,
            "message": "Selfie photo matches with reference photo",
            "score": 0.992796
        }
    },
    "imageLivenessVerificationResult": {
        "data": {
            "code": 1043,
            "message": "Selfie photo is a live photo",
            "score": 0.066661
        }
    },
    "blacklistCheckResult": {
        "faceReferences": [
            {
                "faceId": "f4640eae-5e10-4405-99ea-051826756fb2",
                "matchScore": 1.0
            }
        ]
    }
}

HTTP Status Code : 400

Error JSON Response for Front Side and Back Side - With Error

{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
​   "errors": [
        {
            "message": "Verification failed: Image is blacklisted.",
            "code": 5801,
            "operations": [
                "imageFaceMatchVerification"
            ]
        }
    ], 
    "imageLivenessVerificationResult": {
        "data": {
            "code": 1043,
            "message": "Selfie photo is a live photo",
            "score": 0.066661
        }
    },
     "blacklistCheckResult": {
        "faceReferences": [
            {
                "faceId": "bdc41279-d391-4fc9-8d94-972661fae720",
                "matchScore": 1.0
            }
        ]
    }
}