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

# Obtener sesión biométrica actual

> Recupera la sesión biométrica embebida más reciente de una entidad — mismo patrón que GET /api/kyc/entities/:entityId/current para validaciones KYC.

## Descripción general

Este endpoint devuelve la **sesión biométrica más reciente** de una entidad (ordenada por `createdAt`), **sin importar el estado**: `pending`, `in_progress`, `approved`, `rejected`, etc.

Es el equivalente biométrico de `GET /api/kyc/entities/{entityId}/current` para validaciones KYC.

<Note>
  Si la entidad nunca tuvo una sesión biométrica, la API responde **`200` con `null`** (no 404), igual que el endpoint KYC actual.
</Note>

## Cuándo usarlo

* **Recuperar una sesión pendiente** para embeber de nuevo el `sessionUrl` o cancelarla
* **Consultar el estado** del último intento biométrico (`status`, `rejectionCode`, `decision`)
* **Resolver `ACTIVE_SESSION_EXISTS`** al crear una nueva sesión: el `id` de la sesión activa está en este endpoint (o en `activeSessionId` del error 409)

## Solicitud

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

### Encabezados

```json theme={null}
{
  "Authorization": "Bearer TU_API_KEY",
  "X-Organization-ID": "uuid-de-tu-organizacion"
}
```

## Respuesta

### 200 OK — sesión encontrada

```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 — sin sesiones

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

## Flujo recomendado

1. `POST /api/kyc/biometric/sessions` → guardar `id` y `sessionUrl`
2. Embeber `sessionUrl` en iframe
3. Polling: `GET /api/kyc/biometric/entities/{entityId}/current` o `GET /api/kyc/biometric/sessions/{id}`
4. Si necesitás reiniciar: `POST /api/kyc/biometric/sessions/{id}/cancel` (solo `pending` / `in_progress`)

## Diferencia con `currentSessionId` en el listado

`GET /api/kyc/biometric/sessions?entityId=...` incluye `currentSessionId`: es la última sesión **`approved`** (verificación biométrica vigente). Este endpoint `/current` devuelve la **última sesión creada**, que puede estar `pending`.

| Campo / endpoint                     | Qué representa                          |
| ------------------------------------ | --------------------------------------- |
| `GET .../entities/:entityId/current` | Última sesión creada (cualquier estado) |
| `currentSessionId` en listado        | Última sesión **aprobada**              |

## Error al crear segunda sesión

Si intentás crear otra sesión con una activa (`pending` / `in_progress`), recibís `409 ACTIVE_SESSION_EXISTS` con el ID bloqueante:

```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á con `POST /api/kyc/biometric/sessions/{activeSessionId}/cancel` y volvé a crear.

## Endpoints relacionados

* [Sesión biométrica embebida](/es/use-cases/kyc/embedded-biometric) — crear sesión
* [Eventos webhook biométricos](/es/webhooks/events/biometric-events)