Skip to main content
POST
/
api
/
kyc
/
biometric
/
sessions
Embedded Biometric Session
curl --request POST \
  --url http://api.gu1.ai/api/kyc/biometric/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityId": "<string>",
  "webhookUrl": "<string>",
  "callback": "<string>",
  "language": "<string>",
  "workflowId": "<string>"
}
'

​
Overview

Embedded Biometric lets you re-verify that the person completing a flow is the same individual who passed KYC earlier. Unlike the synchronous Biometric Check (where your app uploads a selfie), this flow uses a hosted capture UI that Gu1 returns as sessionUrl. Your app embeds that URL in an iframe (or opens a redirect) so liveness and face capture run in a controlled environment.
Use status from the API or webhook as the biometric result. Gu1 runs the full session lifecycle and may set rejected after organization policies (cross-entity checks, face-match score thresholds).

​
Prerequisites

  1. Approved KYC in Gu1 for the person entity (status: approved on a session-based validation).
  2. Reference portrait available from that KYC (selfie stored when the validation was approved). Required for session create (NO_PORTRAIT if missing).
  3. KYC enabled for your organization (same API key and permissions as session-based validation). Gu1 provisions the internal hosted-capture configuration; integrators do not set workflows or extra secrets. If your org is not provisioned yet, create may return BIOMETRIC_WORKFLOW_NOT_CONFIGURED (400) — contact your Gu1 account team.
  4. Gu1 Biometric active for your organization (global_gueno_biometric_kyc). If not enabled, create returns NOT_ENABLED (403) — request activation from Gu1.

​
Flow

​
Create session

POST https://api.gu1.ai/api/kyc/biometric/sessions

​
Body

​
entityId
string
required
UUID of the person entity with approved KYC.
​
webhookUrl
string
Optional HTTPS endpoint Gu1 POSTs to on terminal statuses (approved, rejected, abandoned, expired). Signed with your KYC webhook secret when configured.
​
callback
string
Optional redirect URL after the user finishes in the hosted UI.
​
language
string
UI language, e.g. es, en, pt.
​
workflowId
string
Optional override for the biometric workflow ID (otherwise from org KYC settings).

​
Response 201

{
  "id": "bio-session-uuid",
  "entityId": "entity-uuid",
  "status": "pending",
  "sessionUrl": "https://verify.example.com/session/...",
  "iframeAllow": "camera; microphone; fullscreen; autoplay; encrypted-media",
  "mode": "face_match",
  "hostedSessionId": "hosted-session-id"
}

​
Embed in your app

<iframe
  src="{{ sessionUrl }}"
  style="width: 100%; height: 700px; border: none;"
  allow="{{ iframeAllow }}"
></iframe>
Alternatives: full-page redirect to sessionUrl, or a compatible Web SDK initialized with the same URL.

​
Poll or sync status

  • GET /api/kyc/biometric/sessions/:id — current Gu1 status for one session.
  • GET /api/kyc/biometric/entities/:entityId/current — current session = latest with status: approved (by completedAt). Newer rejected, pending, or in_progress attempts do not replace a prior approval. Entity list responses include currentSessionId with the same rule.
  • POST /api/kyc/biometric/sessions/:id/sync — refresh from provider if webhooks are delayed.
  • POST /api/kyc/biometric/sessions/:id/cancel — manually cancel pending or in_progress sessions (marks cancelled in Gu1).
The platform may report In Review while capture is reviewed; Gu1 maps that to in_progress until the final verdict (approved or rejected). Only terminal outcome states define the entity current session.

​
Webhooks

Two channels:
  1. Per-request webhookUrl — only if you sent it in POST /sessions; fires on terminal status.
  2. Organization webhooks — subscribe to biometric.session_* events in Webhook configuration. See Biometric webhook events.

​
Comparison with synchronous biometric

POST /api/kyc/biometricPOST /api/kyc/biometric/sessions
CaptureYour app sends imageHosted UI (iframe)
Fraud resistanceLowerHigher (liveness in hosted UI)
AsyncNoYes
webhookUrl per requestNoYes
For step-up authentication and login flows, prefer embedded sessions.