> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/shared-biometric-components/evaluate-passive-liveness.md).

# Evaluate Passive Liveness

This service performs a **liveness check** using the **selfie image** provided by the user.

### Endpoint

```
POST /services/evaluatePassiveLiveness
```

### Headers

| Name          | Type   | Required | Description                                                |
| ------------- | ------ | -------- | ---------------------------------------------------------- |
| **x-api-key** | string | **Yes**  | Authorization API key for access.                          |
| **family**    | string | No       | Value: **OnBoarding**. Required with the Tracking service. |

{% hint style="info" %}
All calls to the Tracking Endpoints with **Identity Platform** must include the `family`.
{% endhint %}

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter              | Type   | Required | Description                                                                                       |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `imageBuffer`          | string | **Yes**  | **Base64-encoded image** of the user's face. The supported formats are **JPEG** and **PNG**.      |
| `tracking`             | object | No       | Object representing the required tracking information.                                            |
| `tracking.extraData`   | string | No       | Token generated by the SDK Mobile/Web. Contains tracking information tokenized with the Platform. |
| `tracking.operationId` | string | No       | Operation identifier generated by the SDK Mobile/Web.                                             |

#### Example Request

```json
{
  "imageBuffer": "iVBORw0KGgoAAAANSUhEUgAAAAE...",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

{% hint style="warning" %}
**Maximum request size: 6 MB.** The Base64 image (`imageBuffer`) and the remaining fields count toward this limit, with \~33% overhead compared to the original file (maximum original file size \~4.5 MB). Compressed JPEG images of no more than 1–2 MB are recommended. If the limit is exceeded, the gateway responds `413` without processing the request. See [Request Size Limit](https://docs.facephi.com/pages/bc7bee9358079d52bafa44ad281828eb424e96fe#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).
{% endhint %}

### Responses

#### `200` Success

#### Response Parameters

| Parameter               | Type    | Description                                                                                                           |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`     | integer | Code indicating the **overall result** of the service execution. See [Service Result Code](#service-result-code)      |
| `serviceResultLog`      | string  | Descriptive field for the result of the service execution. Includes details when an error or exception occurs.        |
| `serviceTime`           | string  | Total response time **(milliseconds)**.                                                                               |
| `serviceTransactionId`  | string  | Transaction identifier associated with the request processed by the API.                                              |
| `serviceLivenessResult` | integer | Code indicating the **result of the passive liveness check**. See [Service Liveness Result](#service-liveness-result) |

#### Service Result Code

The `serviceResultCode` indicates the overall result of the service execution:

| serviceResultCode | Description                                                                       | HTTP Code |
| ----------------- | --------------------------------------------------------------------------------- | --------- |
| 0                 | The service execution was successful; the module processed the request correctly. | 200       |

#### Service Liveness Result

The `serviceLivenessResult` indicates the result of the passive liveness check evaluation:

| Code | Result                          | Description                                                                                                |
| ---- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| 0    | None                            | The liveness check could not be evaluated.                                                                 |
| 1    | Spoof                           | DEPRECATED. Use 'NoLive' instead.                                                                          |
| 2    | Uncertain                       | DEPRECATED                                                                                                 |
| 3    | Live                            | The subject is assumed to be alive.                                                                        |
| 4    | NoneBecauseBadQuality           | The liveness check could not be evaluated due to poor image quality.                                       |
| 5    | NoneBecauseFaceTooClose         | The liveness check could not be evaluated because the detected faces are too close to the edges.           |
| 6    | NoneBecauseFaceNotFound         | The liveness check could not be evaluated because no faces were detected.                                  |
| 7    | NoneBecauseFaceTooSmall         | The liveness check could not be evaluated because the detected faces are too small.                        |
| 8    | NoneBecauseAngleTooLarge        | The liveness check could not be evaluated because the angle between the faces exceeds the permitted limit. |
| 9    | NoneBecauseImageDataError       | The liveness check could not be evaluated due to errors in the image format.                               |
| 10   | NoneBecauseInternalError        | The liveness check could not be evaluated due to an internal error.                                        |
| 11   | NoneBecauseImagePreprocessError | The liveness check could not be evaluated due to an image preprocessing error.                             |
| 12   | NoneBecauseTooManyFaces         | The liveness check could not be evaluated because too many faces were detected in the image.               |
| 13   | NoneBecauseFaceTooCloseToBorder | The liveness check could not be evaluated because the face is too close to the edge.                       |
| 14   | NoneBecauseFaceCropped          | The liveness check could not be evaluated because the face is cropped.                                     |
| 15   | NoneBecauseLicenseError         | The liveness check could not be evaluated due to a license error.                                          |
| 16   | NoneBecauseFaceOccluded         | The liveness check could not be evaluated because the face is occluded.                                    |
| 17   | NoLive                          | No liveness detected.                                                                                      |
| 18   | NoneBecauseEyesClosed           | The liveness check could not be evaluated because the person's eyes are closed.                            |

#### Example response: Live

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "Live",
  "serviceTime": "799",
  "serviceTransactionId": "35d93da8-b843-4033-8e78-c0aabedcef8b",
  "serviceLivenessResult": 3
}
```

#### Example response: NoLive

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "NoLive",
  "serviceTime": "81",
  "serviceTransactionId": "3f332c81-3dfa-4952-b593-20e3b5651b5b",
  "serviceLivenessResult": 0
}
```

#### `400` Bad Request

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Unauthorized

```json
{
  "message": "Unauthorized"
}
```

#### `403` Forbidden

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `413` Payload Too Large

The request exceeds the maximum allowed size. The gateway rejects it **without processing it**: the response does not include `serviceResultCode` or `serviceTransactionId`. See [Request size limit](https://docs.facephi.com/pages/bc7bee9358079d52bafa44ad281828eb424e96fe#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).

Request larger than 6 MB and up to 10 MB (`Content-Type: application/json`):

```json
{
  "message": "Request Too Long"
}
```

Request larger than 10 MB (10,485,760 bytes) (`Content-Type: text; charset=utf-8`, plain text, not JSON):

```
HTTP content length exceeded 10485760 bytes.
```

#### `502` Bad Gateway

```json
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Gateway Timeout

```json
{
  "message": "Endpoint request timed out"
}
```
