Attempt

An attempt represents a biometric check performed for an applicant. It includes the user's environment data, the submitted biometrics, and the result of the check. An attempt cannot exist without being linked to an applicant.

Attempt biometric data

Biometric data is required in every attempt. It is sent along with the request either by the web component or through a direct request to the publicapi.

Mandatory data:

• Attempt Reference Frame: contains a full-face face in high-quality lighting. This frame is used for all single-frame attempt checks.

Non-mandatory data:

• Liveness-reflection video: captures the reflection of light from the screen on the user's face. This video is used for liveness-reflection verification and is not needed if the check is disabled.
• Motion-control video: records the user's head movements based on the required motion patterns. This video is used for motion-control verification and is not needed if the check is disabled.

Checks

A check is the outcome of processing any attempt data. Each check has a verdict that indicates the success of the processing. In addition, some checks include a score, which is a numerical representation of the result. For checks with a score, the threshold value can be customized, determining the score level at which the verdict is considered successful.

The overall verdict of an attempt is determined by aggregating the verdicts of all executed checks. If any check fails, the overall verdict will be negative.

Check results display locations

In the API, the results of checks are displayed in the validations block. If a check was performed, the verdict field will contain a boolean indicating the result. If no check was performed, the verdict field will be null. The score for each check is stored in the corresponding score field.

Example of checking liveness by photo in the API response:

"validations": {
    "liveness": {
        "verdict": true,
        "details": [
            {
                "name": "FaceLiveness",
                "verdict": true,
                "score": 0.9999389,
                "additionalInfo": {
                    "attackType": "none",
                    "attackTypeConfidence": 0.9999389
                }
            },
            ...
        ]
    },
   ...
}

Example of displaying the check on the dashboard:

• If the check is successful, the check icon will be green.
• If the check fails, the check icon will be red.
• If no check was performed, the check icon will be gray.

List of checks

The checks are organized into three blocks:

• Liveness: Verifies the authenticity of the biometric data.
• Quality: Assesses the quality of the biometric data.
• Matching: Compares faces from the biometric data.

The liveness block consists of:

• Single-frame liveness: Verifies face liveness from a reference frame.
• Liveness-reflection: Verifies face liveness from the liveness-reflection video.

The quality block consists of:

• Photo quality check: Assesses the quality of the reference frame.

The matching block consists of:

• Face similarity: Compares the face from the reference frame with the face from the applicant's biometrics at authorization, and with the found duplicate in the face database at registration.
• Face similarity from liveness-reflection video: Compares the face from the reference frame with the face from the liveness-reflection video.
• Face similarity from motion-control video: Compares the face from the reference frame with the face from the motion-control video.

note

If the single-frame liveness check fails, data on the most probable type of attack and its confidence will be added to the verdict and score.

List of attack types:

• Replay: A photo of a person displayed on any screen.

• Photo: A photo of the person, not cropped to the contour.

• Regions: A contoured photo of the person or just the face.

• 2D-mask: A photo of the person cropped to the contour and "placed" on the face of a real person.

• 3D-mask: A 3D mask used to spoof the system.

Metadata

Attempt metadata refers to data about the environment of the user who submitted the biometrics. This includes information such as IP address, device timezone, device type, browser version, and other similar details.

While metadata helps identify potential risks, it primarily serves as background information.

note

Attempt metadata may not be saved when submitting biometrics through the API if the relevant request fields are not filled in.

Risks

A risk is a pattern in the data of an attempt that may indicate fraudulent actions on the user's part. Risks can be in three states:

Active

When a risk is triggered, it causes the attempt to fail.

An example of a triggered risk in the API response to an attempt request:

{
    "applicantId": "c9df2d99-9bba-4f4e-a967-ff215f80145b",
    "attemptId": 1014,
    ...
    "hasRiskEvents": true,
    ...
    "riskEvents": [
        {
          "created": "2025-03-06T10:49:10.630948Z",
          "riskNumber": 9,
          "riskName": "UntrustedIp",
          "isActive": true
        },
        {
          "created": "2025-03-06T10:49:10.630954Z",
          "riskNumber": 11,
          "riskName": "UntrustedDevice",
          "isActive": false
        }
    ],
}

An example of a triggered risk on the attempt page:

Not Active

Triggering a risk causes it to be saved to the attempt, but it does not affect the attempt's verdict.

An example of a triggered risk in the API response to an attempt request:

{
    "applicantId": "c9df2d99-9bba-4f4e-a967-ff215f80145b",
    "attemptId": 1014,
    ...
    "hasRiskEvents": false,
    ...
    "riskEvents": [
        {
          "created": "2025-03-06T10:49:10.630948Z",
          "riskNumber": 9,
          "riskName": "UntrustedIp",
          "isActive": false
        },
        {
          "created": "2025-03-06T10:49:10.630954Z",
          "riskNumber": 11,
          "riskName": "UntrustedDevice",
          "isActive": false
        }
    ],
}

An example of a triggered risk on the attempt page:

Disabled

Risk checking is fully disabled in the system.

Attempt statuses

The attempt statuses indicate the verdict made when the user's data was checked and reflect the system's state at the time the data was processed.

Attempt status display locations

In API responses, the attempt status is stored in the status field (numeric representation).

An example of an API response containing attempt data:

{
  "applicantId": "78c57b83-9420-404e-bc7e-9edd1c131e55",
  "attemptId": 128,
  ...
  "status": 1
}

In the dashboard, the status of the selected attempt can be viewed in the detailed information section of the applicant.

Description of attempted statuses

Status name	Status number	Status description
Success	0	These attempts successfully passed all checks.
Fail	1	Attempt's data have failed any kind of check.
InvalidData	2	The verification data does not match the required data. For example, there is no face in the reference photo or there are no recorded videos, although they were required.
Error	3	An error occurred on the server while processing the attempt.

note

The InvalidData status is typically caused by incorrectly submitted biometric data. If the data is submitted correctly, ensure that the configuration of the browser-side web component is synchronized with the server-side configuration. Otherwise, the browser-side component may not be sending the data required by the server.