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

# Get Current Biometric Session

> Retrieve the latest embedded biometric session for an entity — same pattern as GET /api/kyc/entities/:entityId/current for KYC validations.

## Overview

This endpoint returns the **most recent biometric session** for an entity (by `createdAt`), **regardless of status**: `pending`, `in_progress`, `approved`, `rejected`, etc.

It mirrors `GET /api/kyc/entities/{entityId}/current` for KYC validations.

<Note>
  If the entity has never had a biometric session, the API responds with **`200` and `null`** (not 404), same as the KYC current endpoint.
</Note>

## When to Use

* **Recover a pending session** to re-embed `sessionUrl` or cancel it
* **Check status** of the latest biometric attempt (`status`, `rejectionCode`, `decision`)
* **Resolve `ACTIVE_SESSION_EXISTS`** when creating a new session: the active session `id` is here (or in `activeSessionId` on the 409 error)

## Request

```
GET https://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current
```

### Headers

```json theme={null}
{
  "Authorization": "Bearer YOUR_API_KEY",
  "X-Organization-ID": "your-organization-uuid"
}
```

## Response

### 200 OK — session found

```json theme={null}
{
  "id": "7618e10c-b1b1-408b-b361-1901077ced73",
  "entityId": "c16b457b-500a-4250-aefe-6d69bdf71fb2",
  "organizationId": "org-uuid",
  "status": "pending",
  "mode": "face_match",
  "sessionUrl": "https://kyc.example.com/session/abc123",
  "hostedSessionId": "e291f904-9c3f-490e-a51e-73434a14ba9a",
  "iframeAllow": "camera; microphone; fullscreen; autoplay; encrypted-media",
  "rejectionCode": null,
  "rejectionMessage": null,
  "createdAt": "2026-06-19T14:40:00.000Z",
  "updatedAt": "2026-06-19T14:40:00.000Z",
  "completedAt": null
}
```

### 200 OK — no sessions

```json theme={null}
null
```

## Recommended Flow

1. `POST /api/kyc/biometric/sessions` → store `id` and `sessionUrl`
2. Embed `sessionUrl` in an iframe
3. Poll: `GET /api/kyc/biometric/entities/{entityId}/current` or `GET /api/kyc/biometric/sessions/{id}`
4. To restart: `POST /api/kyc/biometric/sessions/{id}/cancel` (`pending` / `in_progress` only)

## Difference From List `currentSessionId`

`GET /api/kyc/biometric/sessions?entityId=...` includes `currentSessionId`: the latest **`approved`** session (active biometric verification). This `/current` endpoint returns the **latest created session**, which may be `pending`.

| Field / endpoint                     | Meaning                             |
| ------------------------------------ | ----------------------------------- |
| `GET .../entities/:entityId/current` | Latest created session (any status) |
| `currentSessionId` in list           | Latest **approved** session         |

## Error When Creating a Second Session

If you try to create another session while one is active (`pending` / `in_progress`), you get `409 ACTIVE_SESSION_EXISTS` with the blocking ID:

```json theme={null}
{
  "error": "ACTIVE_SESSION_EXISTS",
  "message": "Cannot create new biometric session. There is already a pending session for this entity. Please cancel or complete the existing session first.",
  "activeSessionId": "7618e10c-b1b1-408b-b361-1901077ced73"
}
```

Cancel with `POST /api/kyc/biometric/sessions/{activeSessionId}/cancel`, then create again.

## Related

* [Embedded biometric session](/en/use-cases/kyc/embedded-biometric) — create session
* [Biometric webhook events](/en/webhooks/events/biometric-events)