> 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**  | Access authorization API Key.                              |
| **family**    | string | No       | Value: **Onboarding**. Required with the tracking service. |

{% hint style="info" %}
All calls to the Endpoints for tracking with **Identity Platform** must contain the header `family`.
{% endhint %}

### Request body

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

#### Parameters

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

#### Request example

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

### Responses

#### `200` Success

#### Response parameters

| Parameter               | Type    | Description                                                                                                               |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`     | integer | Code that indicates 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 there is an error or exception.          |
| `serviceTime`           | string  | Total response time **(milliseconds)**.                                                                                   |
| `serviceTransactionId`  | string  | Transaction identifier associated with the request processed by the API.                                                  |
| `serviceLivenessResult` | integer | Code that indicates 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 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 error in image preprocessing.                      |
| 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.                        |

#### Response example: Live

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

#### Response example: 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"
}
```

#### `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"
}
```