Liveness Status API

The Liveness Transaction Details API allows partners to get the Liveness detection result of Liveness API and Liveness SDK result. This can be done by using the unique transaction ID which returned when invoking liveness API or from SDK liveness output.

Liveness API

GET https://{vida.host}/biometrics/v2/services/face/liveliness?transactionId={UUID}

Headers

Name	Type	Description
Authorization*		OAuth access token. Get the token by calling the Authentication API

API Response

Transaction Details Found Successfully

Case 1 : Liveness transacion completed successfully with scores below threshold.

HTTP Status Code: 200

JSON Response

{
    "data": {
        "transaction": {
            "transactionId": "edfc6404-9e63-4c75-b7a3-d0f27597661e",
            "transactionCode": 1043
        },
        "scores": [
            {
                "scoreName": "LIVENESS",
                "scoreValue": 0.910008
            },
            {
                "scoreName": "IMAGE_MANIPULATION",
                "scoreValue": 0.910211
            }
        ],
        "image": "Base64 image"
    }
}

Case 2 : Liveness transaction completed successfully with scores above threshold.

HTTP Status Code: 200

JSON Response

{
    "data": {
        "transaction": {
            "transactionId": "98d3e451-e966-4a61-9bd4-f8fcb935f04f",
            "transactionCode": 1041
        },
        "scores": [
            {
                "scoreName": "LIVENESS",
                "scoreValue": 0.999674
            },
            {
                "scoreName": "IMAGE_MANIPULATION",
                "scoreValue": 0.971477
            }
        ],
        "image": "Base64 image"
    }
}

Case 3 : Liveness transaction failed due to particular reason.

HTTP Status Code: 200

JSON Response

{
    "data": {
        "transaction": {
            "transactionId": "28b343d0-1479-4b00-bc73-5e16c95afa56",
            "transactionCode": 10001
        },
        "errors": [
            {
                "code": 1063,
                "title": "Image Quality Is Below Threshold",
                "detail": "Unnatural colour"
            },
            {
                "code": 1075,
                "title": "Image Quality Is Below Threshold",
                "detail": "Over Exposure"
            },
            {
                "code": 1076,
                "title": "Image Quality Is Below Threshold",
                "detail": "Image Is Blur"
            }
        ],
        "image": "Base64 image"
    }
}

Transaction Details Not Found

HTTP Status Code: 404

JSON Response

{
    "transactionId": "48f93047-38cb-444d-b557-c72d8d6db185",
    "errors": [
        {
            "code": 1602,
            "title": "Transaction Not Found",
            "detail": "Transaction Not Found: 48f93047-38cb-444d-b557-c72d8d6db185"
        }
    ]
}

---

Liveness Fraud Ops Transaction Details

VIDA Liveness Fraud Ops is a near-real-time manual fraud review system for VIDA liveness service. When your system accepts a user's liveness check based on VIDA’s automated evaluation, Fraud Ops intercepts that session for deeper inspection — especially when the session score passes the AI threshold but may still exhibit signs of spoofing.

When VIDA detects potential fraud through its Fraud Ops, by a specially-trained human, you can receive the notification via webhook, or actively hit the Liveness Transaction Details API with added details.

API Endpoint

GET https://{vida.host}/biometrics/v2/services/face/liveliness?transactionId={UUID}

Headers

Name	Type	Description
Authorization*		OAuth access token. Get the token by calling the Authentication API

API Response

{
    "data": {
        "transaction": {
           ... //same format
        },
        "scores": [
           ... //same format
        ],
        "manualReview": {
            "ticketId": "01K06WXBN8JSG24E0GPADN1231",
            "assessment": "SPOOF",
            "reason": "Injection Attack-Face Manipulation"
        },
        "image": "<base64>"
    }
}

Field	Type	Description
manualReview	JSON Object	Details of manual review from the queried liveness transaction
ticketId	string	Unique reference ID to the manual review ticket, for auditing or support purpose
assessment	string	Result of the manual review by specially-trained human. SPOOF indicates a confirmed fraud by human agent
reason	string	Brief explanation of the attack and spoof type