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

# Biometric Authentication

> Re-authenticate users by comparing a new selfie against their approved session.

Compare a new selfie against the original selfie from an approved verification session. Ideal for step-up authentication, login verification, or high-value transaction confirmation.

## Authenticate

<ParamField body="session_id" type="string" required>
  The ID of an **approved** verification session to compare against.
</ParamField>

<ParamField body="file" type="file" required>
  New selfie image. Accepted: `jpg`, `jpeg`, `png`. Max: 10 MB.
</ParamField>

<ParamField body="threshold" type="number">
  Minimum similarity score to consider a match (50–100). Default: `80`.
</ParamField>

<ParamField body="device_info" type="object">
  Optional device metadata (model, OS, IP).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    "https://verilock.io/api/v1/auth/biometric" \
    -H "Authorization: Bearer qi_live_your_api_key_here" \
    -F "session_id=ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
    -F "file=@new_selfie.jpg" \
    -F "threshold=85"
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://verilock.io/api/v1/auth/biometric",
      headers={"Authorization": "Bearer qi_live_your_api_key_here"},
      files={"file": open("new_selfie.jpg", "rb")},
      data={
          "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "threshold": 85,
      },
  )
  ```

  ```javascript Node.js theme={null}
  const form = new FormData();
  form.append('session_id', 'ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890');
  form.append('file', fs.createReadStream('new_selfie.jpg'));
  form.append('threshold', '85');

  const res = await fetch('https://verilock.io/api/v1/auth/biometric', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer qi_live_your_api_key_here' },
    body: form,
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 202 Accepted theme={null}
  {
    "id": "bio_f1e2d3c4-b5a6-9870-fedc-ba0987654321",
    "status": "processing",
    "message": "Biometric authentication started."
  }
  ```
</ResponseExample>

## Get Result

```
GET /v1/auth/biometric/{id}
```

<ResponseExample>
  ```json 200 Match theme={null}
  {
    "id": "bio_f1e2d3c4-...",
    "session_id": "ses_a1b2c3d4-...",
    "result": "match",
    "similarity": 94.32,
    "liveness_score": 87.50,
    "liveness_passed": true,
    "threshold_used": 85.00,
    "created_at": "2026-03-16T14:30:00Z"
  }
  ```

  ```json 200 No Match theme={null}
  {
    "id": "bio_f1e2d3c4-...",
    "session_id": "ses_a1b2c3d4-...",
    "result": "no_match",
    "similarity": 45.10,
    "liveness_score": 82.00,
    "liveness_passed": true,
    "threshold_used": 85.00,
    "created_at": "2026-03-16T14:30:00Z"
  }
  ```
</ResponseExample>

## Result Values

| Result     | Description                                        |
| ---------- | -------------------------------------------------- |
| `match`    | Similarity meets threshold **and** liveness passed |
| `no_match` | Similarity below threshold or liveness failed      |
| `error`    | Processing error (no face detected, file corrupt)  |
| `pending`  | Still processing                                   |

<Note>
  Processing is asynchronous. Poll `GET /auth/biometric/{id}` or subscribe to the `biometric.completed` webhook event.
</Note>