Skip to main content
GET
/
api
/
kyc
/
biometric
/
entities
/
{entityId}
/
current
Get Current Biometric Session
curl --request GET \
  --url http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current \
  --header 'Authorization: Bearer <token>'

​
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.
If the entity has never had a biometric session, the API responds with 200 and null (not 404), same as the KYC current endpoint.

​
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

{
  "Authorization": "Bearer YOUR_API_KEY",
  "X-Organization-ID": "your-organization-uuid"
}

​
Response

​
200 OK — session found

{
  "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

null
  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 / endpointMeaning
GET .../entities/:entityId/currentLatest created session (any status)
currentSessionId in listLatest 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: 
{
  "error": "ACTIVE_SESSION_EXISTS",
  "message": "The latest biometric session for this entity is still active...",
  "activeSessionId": "7618e10c-b1b1-408b-b361-1901077ced73"
}
Cancel with POST /api/kyc/biometric/sessions/{activeSessionId}/cancel, then create again.