---
title: "Liveness - Rest PKI Core"
description: "Liveness check in Rest PKI Core: verifies that a real person is in front of the screen, detecting fraud attempts with photos, videos or masks."
canonical: "https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/liveness"
locale: "en"
product: "Rest PKI Core"
last_updated: "2026-10-12"
---

# Liveness - Rest PKI Core

- Checks that a real person is present on the other side of the screen, detecting fraud attempts with photos, videos or masks.
- It does not identify the person (who they are): it only attests the presence of a live human being.
- The photo captured from the user can be retrieved at the end of the session.

## Creating the session

To create a liveness session, use the `StartLivenessSessionAsync` method of the client libs, passing a `StartLivenessSessionRequest`.

This method makes a `POST` request to `/api/bio/sessions/liveness` [(Swagger)](https://core.pki.rest/swagger/index.html#operations-BioSessions-post_api_bio_sessions_liveness).

### Parameters (`StartLivenessSessionRequest`)
| **Parameter**                     | **Required?**    | **Type** | **Description** |
| --------------------------------- | ---------------- | -------- | --------------- |
| **ReturnUrl**                     | Conditional*     | String   | URL to redirect the user to after the biometric check. [(see details)](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#redirect-flow-returnurl)
| **TrustedOrigin**                 | Conditional*     | String   | URL of your site where the widget is embedded. [(see details)](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#embedded-flow-widgettrustedorigin)
| **PlatformPreference**            | No               | Enum     | Sets the platform preference and the QR code behavior. [(see details)](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#general-parameters)
| **SubjectIdentifier**             | No               | String   | External identifier of the user. [(see details)](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#user-identifier-subjectidentifier)
| **FaceCaptureProvider**           | No               | Enum     | Sets the biometric provider. [(see details)](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#face-capture-session-parameters)
| **CaptureIdentificationDocument** | No               | Bool     | If enabled, the user must capture an ID document right after the liveness check.

> **Tip**
>
> *You must pass at least one of the two parameters ([see the difference between ReturnUrl and TrustedOrigin](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#frontend-flows)):
> - `ReturnUrl` (for the redirect flow)
> - `TrustedOrigin` (for the widget)

> Optional parameters can be left blank (`null`) and are filled in automatically with the system defaults.

> **Note**
>
> Older samples use the `FaceLivenessProvider` parameter, which is obsolete: use `FaceCaptureProvider`. Rest PKI Core only takes
> `FaceLivenessProvider` into account when `FaceCaptureProvider` is not given.

### Response example

```json
{
  "sessionType": "Liveness",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sessionUrl": "string"
}
```
### Frontend integration
Once your backend has obtained the `sessionUrl` from the API, forward it to your frontend. From there, the flow follows the interface you chose:

- **Embedded flow (widget)**: your application passes the URL to the JavaScript component, which starts the capture inside your page.

- **Redirect flow**: your application sends the user to the URL received, where the capture takes place.

> **Tip**
>
> If you are unsure how to implement each model, see [Frontend flows](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#frontend-flows).

---
## Completing the session

To complete a liveness session, use the `CompleteLivenessSessionAsync` method of the client libs, passing a `CompleteBioSessionRequest`.

This method makes a `POST` request to `/api/bio/sessions/liveness/completion` [(Swagger)](https://core.pki.rest/swagger/index.html#operations-BioSessions-post_api_bio_sessions_liveness_completion).

This method is the final step. The ticket can be used only once.

> **Tip**
>
> Call the completion only at the end of the process, sending the ticket you received to validate the result and close the session.

### Response example

```json
{
  "faceLivenessStatus": {
    "provider": "FaceTecLiveness3d",
    "success": true,
    "attemptCount": 0
  },
  "idCaptureStatus": {
    "success": true,
    "matchedFace": true,
    "matchedFaceLevel": 0
  },
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "success": true,
  "resultDataAvailable": true
}
```

#### Field details

* **faceLivenessStatus**:
    * **provider**: provider of the biometric service.
    * **success**: whether the liveness check succeeded.
    * **attemptCount**: number of attempts made by the user.
* **idCaptureStatus**:
    * **success**: whether the document capture succeeded.
    * **matchedFace**: whether the person's face matched the photo on the document.
    * **matchedFaceLevel**: similarity level between the face and the document (`MatchLevel`).
* **sessionId**: unique identifier of the session.
* **success**: overall result of the session.
* **resultDataAvailable**: if `true`, you can fetch the photos collected in the session.

---

## Checking the session status

You can check the current state of a session at any time using its `sessionId`. This is useful to monitor whether the user has started the
session, or whether it has expired, even before it is completed.

> **Tip**
>
> Use `GetLivenessSessionStatusAsync` to follow the progress of an active session by its `sessionId`.

The response of this endpoint is exactly the same as the [response example of `CompleteLivenessSessionAsync`](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/liveness#response-example-1).

**Demos and samples**

- Live demo: [Run a liveness check](https://try.lacunasoftware.com/en/lacuna-bio/run-a-liveness-check)