The document liveness signal in the /start endpoint returns a corresponding document liveness response in the /get-results endpoint.

👍

Document liveness checks can help you evaluate an ID for document fraud. Document liveness is available for both Capture and Direct.

When you include the document_liveness_idrnd signal in the /start request body, we perform three document liveness checks. Check results are returned as part of a documentLivenessIdRnD object in the /get-results response, as follows:

• A screen replay (screenReplay) result. Was the document most likely captured from a device screen or monitor?
• A printed copy (printedCopy) result. Was the document most likely a printed copy or photocopy of a physical ID document?
• A portrait substitution (portraitSubstitution) result. Was the document most likely submitted with an altered or substituted portrait image?

Each of these three results includes a live property [0, 1] to indicate whether the document passed the check. If live is zero (0), then the document did not pass.

To arrive at alive result, we evaluate two other properties for each check: probability and threshold.

• The probability value is a confidence estimate (any number between 0 and 1) that the document passed the check.

👍

A lower probability is a worse result.

• The threshold value is a confidence cutoff that applies to probability. It is typically set at 0.5, which means the probability must be 0.5 or greater for the check to pass. When compared to probability, the threshold parameter determines the live result.

Example document liveness responses

By way of illustration, consider the portraitSubstitution check.

Passed response

If probability is greater than or equal to threshold, then the portraitSubstitution check passed.

In this illustration, the probability is 0.9, which is greater than the threshold of 0.5. Therefore, the live value is 1, meaning the portraitSubstitution check passed.

Here is a sample response showing that part of the result.

"documentLivenessIdRnD": {
                "data": {
                    "front": {
                        "portraitSubstitution": {
                            "live": 1,
                            "threshold": 0.5,
                            "probability": 0.9
                        },
...

Failed response

If probability is less than threshold, then the portraitSubstitution check failed.

In this illustration, the probability is 0.01, which is less than the threshold of 0.5. Therefore, the live value is 0, meaning the portraitSubstitution check failed.

Here is a sample response showing that part of the result.

"documentLivenessIdRnD": {
                "data": {
                    "front": {
                        "portraitSubstitution": {
                            "live": 0,
                            "threshold": 0.5,
                            "probability": 0.01
                        },
...

Overall result

If any one of the three document liveness checks (screenReplay, printedCopy, and portraitSubstitution) returns a live result of 0, then the overall live result is also 0, meaning the document liveness check failed.

Here is a sample response showing an overall live result of 0.

"documentLivenessIdRnD": {
    "data": {
        "front": {
            "portraitSubstitution": {
                "live": 0,
                "threshold": 0.5,
                "probability": 0.01
            },
            "printedCopy": {
                "threshold": 0.5,
                "live": 1,
                "probability": 1.0
            },
            "screenReplay": {
                "live": 1,
                "threshold": 0.5,
                "probability": 1.0
            },
            "live": 0                 // <-- This is the overall result
        }
    },
    "success": true,
    "imageQualityFindings": [],
    "message": "",
    "result": true
}

In this example, the portraitSubstitution check failed with a probablility of 0.01. The printedCopy check and the screenReplay check both passed with a probability of 1.0. However, because probability failed, the overall live result is 0, meaning the document did not pass a document liveness check.

Supported document types

Document liveness checks are optimized for North American DMV-issued IDs. For best results, submit a document_type of na_dl in the /start request.

It is possible to submit another document_type (passport or other). However, the checks are not optimized; therefore, results may vary.