---
title: "Facial identification (1:N Identification) - Rest PKI Core"
description: "1:N facial identification in Rest PKI Core: searches a database of enrollments for the captured face to find whom it belongs to. It may not be enabled."
canonical: "https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/identification"
locale: "en"
product: "Rest PKI Core"
last_updated: "2026-10-12"
---

# Facial identification (1:N Identification) - Rest PKI Core

 - Searches a database of enrollments for the captured face, to find out whom it belongs to.
 - Unlike authentication, it does not start from a known user.

> **Note**
>
> Facial identification is a computationally expensive process, also known as a **1:N search**.
> As a result, this feature may not be enabled on the instance you are integrating with.
> If you are interested in enabling it, **contact us** at [suporte@lacunasoftware.com](mailto:suporte@lacunasoftware.com) to request a
> **demonstration**.

## Creating the session

To create an identification session, use the `StartIdentificationSessionAsync` method of the client libs, passing a
`StartBioIdentificationSessionRequest`.

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

### Parameters (`StartBioIdentificationSessionRequest`)
| **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)
| **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)

> **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.

### Response example

```json
{
  "sessionType": "Identification",
  "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 an identification session, use the `CompleteIdentificationSessionAsync` method of the client libs, passing a
`CompleteBioSessionRequest`.

This method makes a `POST` request to `/api/bio/sessions/identification/completion` [(Swagger)](https://core.pki.rest/swagger/index.html#operations-BioSessions-post_api_bio_sessions_identification_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
{
  "identifiedSubjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "identifiedSubjectIdentifier": "string",
  "failure": "CaptureFailed",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "success": true,
  "resultDataAvailable": true
}
```

#### Field details

* **identifiedSubjectId**: on success, the Id of the enrollment of the person identified.
* **identifiedSubjectIdentifier**: on success, the `SubjectIdentifier` of the person identified.
* **failure**: tells whether a failure occurred during the session; see the list of failures below.
* **sessionId**: Id of the Rest PKI Core session.
* **success**: whether the identification session succeeded.
* **resultDataAvailable**: if `true`, you can fetch the photos collected in the session.

#### Failures

| **Enum**                          | **Description**                                    |
| --------------------------------- | -------------------------------------------------- |
| CaptureFailed                     | The image capture could not be finished. It usually happens when the user interrupts it.
| LivenessFailed                    | The user did not pass the liveness check: the number of attempts exceeded the limit.
| NoMatch                           | The biometric collected did not reach the minimum match with any biometric enrolled in the database.
| BadImage                          | The captured image does not have enough quality to be processed. It may be caused by poor lighting or blur.

## Checking the 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 `GetIdentificationSessionStatusAsync` 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 `CompleteIdentificationSessionAsync`](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/identification#response-example-1).