> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/sdk-lite/setup/backend/result-reference.md).

# Result Reference

This page describes the response of `GET /v1/faces/liveness/attempts/{attemptId}/await`. For how to call it, see [Setup](https://docs.caf.io/sdk-lite/setup/backend/setup.md). For what to do with each result, see [Failure Handling](https://docs.caf.io/sdk-lite/failure-handling/backend/failure-handling.md). For error responses, see [Error Handling](https://docs.caf.io/sdk-lite/error-handling/backend/error-handling.md).

## Fields

| Field                   | Type    | When present                                    | Description                                                                                                                                                        |
| ----------------------- | ------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `requestId`             | String  | Always                                          | Identifier of this request. Use it when you contact support.                                                                                                       |
| `id`                    | String  | Always                                          | Attempt identifier. Same value as `attemptId` / `livenessAttemptId`.                                                                                               |
| `sessionId`             | String  | Always                                          | Liveness session that produced this attempt.                                                                                                                       |
| `status`                | String  | Always                                          | `COMPLETED` or `FAILED`. See [Status](#status).                                                                                                                    |
| `isAlive`               | Boolean | `COMPLETED` only                                | `true` if the capture is a live face; `false` if it is not.                                                                                                        |
| `signals`               | Object  | `COMPLETED` only, when available                | Capture quality indicators. See [Signals](#signals).                                                                                                               |
| `feedbackCode`          | String  | `COMPLETED`, `isAlive=false`, when available    | Technical rejection code. See [Feedback codes](#feedback-codes).                                                                                                   |
| `userFeedbackCode`      | String  | `COMPLETED`, `isAlive=false`, when available    | Guidance code for the next attempt. See [Feedback codes](#feedback-codes).                                                                                         |
| `images`                | Array   | `COMPLETED` only                                | Capture images in Base64. See [Images](#images).                                                                                                                   |
| `isExtraFramesComplete` | Boolean | `COMPLETED` only, when enabled for your account | `true` when all 3 additional frames are available; otherwise `false`. See [Additional frames completeness](#additional-frames-completeness-isextraframescomplete). |
| `createdAt`             | String  | `COMPLETED` only                                | Creation date and time of the attempt (ISO 8601).                                                                                                                  |

### Status

| Value       | Meaning                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `COMPLETED` | The attempt finished and a liveness verdict is available. Read `isAlive`.                                          |
| `FAILED`    | The attempt did not finish with a verdict. `isAlive`, `signals`, `images` and `isExtraFramesComplete` are omitted. |

### Images

| Field    | Type   | Description                                                          |
| -------- | ------ | -------------------------------------------------------------------- |
| `type`   | String | `MAIN` for the primary capture image; `EXTRA` for additional frames. |
| `order`  | Number | Sequence of the additional frame. Present on `EXTRA` images only.    |
| `base64` | String | Image content encoded as Base64.                                     |

When a usable image was captured, `images` contains one `MAIN` image, which has no `order`. It may be followed by up to 3 `EXTRA` frames.

`images` is empty when no usable image was captured. In that case `isAlive` is `false`.

#### Additional frames completeness (`isExtraFramesComplete`)

When enabled for your account, `isExtraFramesComplete` indicates whether the expected additional frames are available:

* `true`: all 3 additional frames are available.
* `false`: otherwise.

This field is omitted if the feature is not enabled for your account, and on attempts that did not complete (`FAILED`).

### Signals

During the capture, the image quality (sharpness, lighting and face position) is assessed, and the capture is checked for a single, consistent face. The `signals` block reports these assessments:

| Field                         | Type    | Description                                                                |
| ----------------------------- | ------- | -------------------------------------------------------------------------- |
| `signals.isImageQualityOk`    | Boolean | `true` when the image has adequate sharpness, lighting and face position.  |
| `signals.isFaceConsistencyOk` | Boolean | `true` when there was a single face, the same one, throughout the capture. |

When `signals` is present, both fields are always present. A `false` value means that the check did not pass, or that it could not be measured.

`signals` can be missing, for example when `status` is `FAILED`. It is then omitted, with no `null` value and no empty object. Treat a missing block as "no quality information", not as `false`.

The signals are informative: they do not change `isAlive`. For how to use them, see [Capture quality signals](https://docs.caf.io/sdk-lite/failure-handling/backend/failure-handling.md#capture-quality-signals).

### Feedback codes

`feedbackCode` and `userFeedbackCode` can be present only when `status` is `COMPLETED` and `isAlive` is `false`. They are always present together. They can still be missing, for example when no usable image was captured. Treat a missing code like `unknown`.

| Field              | Use it for                                                        |
| ------------------ | ----------------------------------------------------------------- |
| `feedbackCode`     | Reason for the rejection, for your own logic, logs and analytics. |
| `userFeedbackCode` | Choosing the message you show the user before a new attempt.      |

`feedbackCode` is the reason for the rejection. `userFeedbackCode` is guidance for the user and corresponds to the SDK failure `type`. It is not the reason for the failure: for suspected attacks it is generic, so don't infer the cause from it.

For how to use them, see [Guiding the user](https://docs.caf.io/sdk-lite/failure-handling/backend/failure-handling.md#guiding-the-user).

**`feedbackCode` values**

| Value                            | Description                                                              |
| -------------------------------- | ------------------------------------------------------------------------ |
| `error`                          | A generic processing or system error occurred.                           |
| `timeout`                        | A processing step exceeded its time limit.                               |
| `network_timeout`                | Connectivity or latency prevented timely completion.                     |
| `frames_blurry`                  | The captured frames were too blurry to assess.                           |
| `suspected_impersonation_attack` | A possible impersonation attempt was detected.                           |
| `suspected_injection_attack`     | A possible digital injection of imagery was detected.                    |
| `suspected_presentation_attack`  | A possible presentation attack, such as a photo or screen, was detected. |
| `user_information_inconclusive`  | There was not enough information to reach a confident decision.          |
| `user_blocked`                   | The user is blocked. A new attempt will not pass.                        |
| `env_too_bright`                 | The capture environment was too bright.                                  |
| `env_too_dark`                   | The capture environment was too dark.                                    |
| `user_cancelled`                 | The user cancelled the session.                                          |
| `user_eyes_closed`               | The user's eyes were closed.                                             |
| `user_glasses`                   | Glasses or eyewear affected the capture.                                 |
| `user_multiple_faces`            | More than one face was detected.                                         |
| `user_obscured_face`             | The face was partially obscured.                                         |
| `user_sunglasses`                | Sunglasses were detected.                                                |
| `processing_fault`               | A processing failure occurred.                                           |
| `unknown`                        | No usable feedback code is available.                                    |

**`userFeedbackCode` values**

Each value, except `user_cancelled`, matches the SDK failure `type` with the same name. For example, `lighting_issues` matches `LIGHTING_ISSUES` on Android and `lightingIssues` on iOS. For the message to show the user, see [Quick Reference](https://docs.caf.io/sdk-lite/failure-handling/mobile/failure-handling.md#quick-reference).

| Value              | Meaning                                           |
| ------------------ | ------------------------------------------------- |
| `lighting_issues`  | Unsuitable lighting.                              |
| `face_not_found`   | Face not found in the guide.                      |
| `eyes_closed`      | Eyes closed.                                      |
| `eyewear`          | Eyewear covering the eyes.                        |
| `obscured_face`    | Face partially covered.                           |
| `multiple_faces`   | More than one face.                               |
| `frames_blurry`    | Blurry image.                                     |
| `motion_issue`     | Movement data could not be used.                  |
| `background_issue` | Background or contrast.                           |
| `device_issue`     | Device or environment.                            |
| `device_restart`   | The device may need a restart.                    |
| `system_error`     | System error.                                     |
| `timeout`          | Time limit reached.                               |
| `processing_fault` | Processing failure.                               |
| `user_not_found`   | User not registered.                              |
| `rejected`         | The user is blocked. A new attempt will not pass. |
| `user_cancelled`   | The user cancelled the capture.                   |
| `unknown`          | No specific guidance is available.                |

New values can be added. Handle `unknown` and any value you don't recognize with a generic message.

## Examples

### Completed, live

```json
{
  "requestId": "bb1ce1fd-5d0d-42af-bb0e-16f56b230a20",
  "id": "01K1XDD6W98M5QM9B8EAZZDV49",
  "sessionId": "01K1XDD6W98M5QM9B8EAZZSESS",
  "status": "COMPLETED",
  "isAlive": true,
  "signals": {
    "isImageQualityOk": true,
    "isFaceConsistencyOk": true
  },
  "images": [
    { "type": "MAIN", "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/..." },
    { "type": "EXTRA", "order": 1, "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/..." },
    { "type": "EXTRA", "order": 2, "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/..." },
    { "type": "EXTRA", "order": 3, "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/..." }
  ],
  "isExtraFramesComplete": true,
  "createdAt": "2026-09-08T08:30:00.000Z"
}
```

### Completed, not live

```json
{
  "requestId": "bb1ce1fd-5d0d-42af-bb0e-16f56b230a20",
  "id": "01K1XDD6W98M5QM9B8EAZZDV49",
  "sessionId": "01K1XDD6W98M5QM9B8EAZZSESS",
  "status": "COMPLETED",
  "isAlive": false,
  "signals": {
    "isImageQualityOk": false,
    "isFaceConsistencyOk": true
  },
  "feedbackCode": "user_information_inconclusive",
  "userFeedbackCode": "lighting_issues",
  "images": [
    { "type": "MAIN", "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/..." }
  ],
  "isExtraFramesComplete": false,
  "createdAt": "2026-09-08T08:30:00.000Z"
}
```

When no usable image was captured, `images` is empty (`[]`).

### Did not finish

```json
{
  "requestId": "bb1ce1fd-5d0d-42af-bb0e-16f56b230a20",
  "id": "01K1XDD6W98M5QM9B8EAZZDV49",
  "sessionId": "01K1XDD6W98M5QM9B8EAZZSESS",
  "status": "FAILED"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/sdk-lite/setup/backend/result-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
