> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started

> Learn about Facial Biometrics, its uses, requirements, and reference modes.

**Facial Biometrics** verifies that the person in front of the camera matches a reference image. Unlike [full biometrics](https://docs.jelou.ai/en/guides/integraciones/identidad/connect-biometrics.md), it does not capture or analyze an identity document.

> [!NOTE]
>
> The experience uses liveness and facial comparison. The reference image can come from Ecuador's Civil Registry or from the client, depending on the configured mode.

## What it includes

\| Stage | What it does |
\|---|---|---|
\| **Liveness** | Confirms that a real person is in front of the camera. |
\| **Facial comparison** | Compares the selfie with the reference image and calculates similarity. |

### ✅ Checklist to start without blockers

* Provide a public Terms and Conditions URL.
* Enable camera permissions for the user.
* For the **Civil Registry photo** mode, operate in Ecuador and have the user's ID and fingerprint code.
* For the **Photo supplied in the flow** mode, provide `referenceImageUrl` from the Biometrics node or Memory.
* Keep the reference image available while the session is valid.
* Biometric 1:N search is outside this product.

## Reference modes

> [accordion] government
>
> Queries the Civil Registry photo with the user's ID number and fingerprint code. Available only in Ecuador.
>
> * Configure `maxGovValidationAttempts`; the webview defaults to 3.
> * The user enters exactly 10 ID digits.
> * The fingerprint code accepts 6 to 10 alphanumeric characters and is converted to uppercase.
> * The camera opens only when the Civil Registry returns the person's photo.

> [accordion] client
>
> Compares the selfie with the image provided by the client through `referenceImageUrl`. Available in any country.
>
> * The URL can come from the same flow or another flow through **Memory**.
> * The image must remain available while the session is active.
> * The user enters no data and sees no document steps.

## Configuration

Configure the mode in the **Biometrics node** when creating the session.

| Field | Mode | Description |
| - | - | - |
| `faceReferenceSource` | Both | `government` or `client`. If omitted, the flow works as full biometrics. |
| `maxGovValidationAttempts` | `government` | Maximum ID validation attempts. Uses 3 when omitted. |
| `referenceImageUrl` | `client` | Reference image URL from the current flow or Memory. |
| `companySettings.facematchThreshold` | Both | Similarity threshold for facial comparison. |

The mode is fixed when the session is created. Later configuration changes do not affect existing sessions.

## How it works

**1. Create the session**

The Biometrics node creates the session in **identity-service** with the selected mode and, for `client`, the reference image.

**2. Open the link**

The webview reads the mode from `/flow-state` and, as a fallback, from `details.faceReferenceSource`.

**3. Validate the reference**

In `government`, the user enters their ID and fingerprint code before the selfie. In `client`, the node already supplied the image.

**4. Complete liveness**

The only capture is a guided selfie with liveness. The webview uses `biometricFlow = ['liveness']`.

**5. Compare faces**

**identity-service** compares the approved selfie with the reference image. The provider is AWS Rekognition.

**6. Deliver the result**

Jelou sends the webhook to the flow or client and returns the user to WhatsApp or `callbackUrl`.

## Inputs and outputs

### Session data

| Variable | Mode | Description |
| - | - | - |
| `details.faceReferenceSource` | Both | `government` or `client`. |
| `details.maxGovValidationAttempts` | `government` | ID validation attempts. |
| `details.referenceImageUrl` | `client` | Reference image URL. |
| `companySettings.facematchThreshold` | Both | Facial comparison threshold. |

### Final webhook

* `document_response.document_check` is skipped with `reason: "not_in_biometric_flow"`.
* In `government`, `gov_response` includes the Civil Registry result.
* In `client`, `gov_response` is skipped with `reason: "face_reference_client"`.
* `facematch_result` uses lowercase values (`approved` or `declined`); liveness and government results use uppercase.
* A failed comparison adds `imageDocumentUrl` and `imageLivenessUrl` to `facematch_response`.

## User experience

> [tab] government — Ecuador
>
> 1. Start and terms screen.
> 2. The user enters their ID and fingerprint code.
> 3. The user completes the liveness selfie.
> 4. Facial comparison is shown without OCR, recapture or manipulation steps.
> 5. The result returns the user to WhatsApp or `callbackUrl`.

> [tab] client
>
> 1. Start and terms screen.
> 2. The user completes liveness without entering data or seeing document information.
> 3. Identity validation runs.
> 4. The result returns the user to WhatsApp or `callbackUrl`.

## Limits and considerations

* The `client` image must remain available for the whole session; an expired signed URL returns `reference_image_unavailable`.
* The flow does not capture documents, run OCR, or detect document recapture or manipulation.
* Biometric 1:N search is outside this product.
* Confirm the exact session duration and `gov_entity_data` format with the backend team.

> [card] [Next: Configuration](https://docs.jelou.ai/en/guides/integraciones/identidad/biometrics-configuration.md)
>
> Configure the Biometrics node and its outputs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.