Skip to main content

# 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 photo 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: face Liveness check.
- Liveness-reflection: Verifies face liveness from the liveness-reflection video. (Experimental feature)
- DeepFake. Checks for signs of DeepFake technology usage. (Experimental feature)

The quality block consists of:

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

note

If the photo fails the quality check, information about the reasons for the failure will be added to the verdict.

List of reasons:

- The image is too sharp.
- The image is too noisy.
- The image has too high dynamic range.
- The face in the image has a large pitch angle.
- The face in the image has a large yaw angle.
- The face extends the boundaries of the image.
- Sunglasses are detected on the face.
- The size of the face in the image is too small relative to the image itself.

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.

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 attempt data 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, you can view the status of the selected attempt in the detailed information section of the applicant.

#### Description of attempted statuses​

A new attempt is created when the user session starts and is given the Unfinished status.

When the session ends up correctly, the attempt status is updated according to the results. If the attempt remains in the Unfinished status for a long time, this indicates a process violation — either the user interrupted the operation, or a critical error occurred in the web component.

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.
Unfinished | 4 | The user session has started but has not yet ended.

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.