Skip to main content
GET
/
api
/
kyc
/
biometric
/
entities
/
{entityId}
/
current
Obter sessão biométrica atual
curl --request GET \
  --url http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current \
  --header 'Authorization: Bearer <token>'

​
Visão geral

Este endpoint retorna a sessão biométrica mais recente de uma entidade (por createdAt), independente do status: pending, in_progress, approved, rejected, etc. É o equivalente biométrico de GET /api/kyc/entities/{entityId}/current para validações KYC.
Se a entidade nunca teve sessão biométrica, a API responde 200 com null (não 404), igual ao endpoint KYC atual.

​
Quando usar

  • Recuperar uma sessão pendente para reembarcar o sessionUrl ou cancelá-la
  • Consultar o status da última tentativa biométrica (status, rejectionCode, decision)
  • Resolver ACTIVE_SESSION_EXISTS ao criar nova sessão: o id da sessão ativa está neste endpoint (ou em activeSessionId no erro 409)

​
Solicitação

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

​
Cabeçalhos

{
  "Authorization": "Bearer SUA_API_KEY",
  "X-Organization-ID": "uuid-da-sua-organizacao"
}

​
Resposta

​
200 OK — sessão encontrada

{
  "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 — sem sessões

null

​
Fluxo recomendado

  1. POST /api/kyc/biometric/sessions → guardar id e sessionUrl
  2. Embarcar sessionUrl em iframe
  3. Polling: GET /api/kyc/biometric/entities/{entityId}/current ou GET /api/kyc/biometric/sessions/{id}
  4. Para reiniciar: POST /api/kyc/biometric/sessions/{id}/cancel (apenas pending / in_progress)

​
Diferença do currentSessionId na listagem

GET /api/kyc/biometric/sessions?entityId=... inclui currentSessionId: a última sessão approved (verificação biométrica vigente). Este /current retorna a última sessão criada, que pode estar pending.
Campo / endpointSignificado
GET .../entities/:entityId/currentÚltima sessão criada (qualquer status)
currentSessionId na listagemÚltima sessão aprovada

​
Erro ao criar segunda sessão

Se tentar criar outra sessão com uma ativa (pending / in_progress), recebe 409 ACTIVE_SESSION_EXISTS com o ID bloqueante: 
{
  "error": "ACTIVE_SESSION_EXISTS",
  "message": "The latest biometric session for this entity is still active...",
  "activeSessionId": "7618e10c-b1b1-408b-b361-1901077ced73"
}
Cancele com POST /api/kyc/biometric/sessions/{activeSessionId}/cancel e crie novamente.

​
Relacionados