Embedded Biometric Session
Biometric
Embedded Biometric Session
Start a hosted biometric re-authentication session after approved KYC β iframe-ready session URL, webhooks, and Gu1 final verdict.
POST
Embedded Biometric Session
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 assessionUrl. Your app embeds that URL in an iframe (or opens a redirect) so liveness and face capture run in a controlled environment.
Prerequisites
- Approved KYC in Gu1 for the person entity (
status: approvedon a session-based validation). - Reference portrait available from that KYC (selfie stored when the validation was approved). Required for session create (
NO_PORTRAITif missing). - 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. - Gu1 Biometric active for your organization (
global_gueno_biometric_kyc). If not enabled, create returnsNOT_ENABLED(403) β request activation from Gu1.
Flow
Create Session
Body
Provide exactly one entity identifier:string
UUID of the person entity with approved KYC.
string
Your external ID for the entity (
entities.externalId in Gu1).string
Tax or document number (CUIT, CPF, DNI, etc.). Gu1 resolves it with normalized match on
entities.tax_id. The entity must exist in Gu1 (404 if not found).Sandbox entity preview:
GET /api/entities/by-tax-id/{taxId} may return a synthetic person (sandboxMock: true, id: null) for catalog test document numbers when no real row exists. That preview is read-only β you still need a persisted entity before POST /sessions.string
Optional HTTPS endpoint Gu1 POSTs to on terminal statuses (
approved, rejected, abandoned, expired). Signed with your KYC webhook secret when configured.string
Optional redirect URL after the user finishes in the hosted UI.
string
UI language, e.g.
es, en, pt.string
Optional override for the biometric workflow ID (otherwise from org KYC settings).
Response 201
In sandbox mock,
status may be approved or rejected immediately (no iframe). See Sandbox mock β Embedded biometric.Recommended Integration Flow
- Ensure the person entity has KYC
approved(session-based validation). - Call
POST /api/kyc/biometric/sessionsonce per user intent. Storeid,sessionUrl, andhostedSessionId. - If the response is
409 ACTIVE_SESSION_EXISTS, cancel withPOST .../sessions/{activeSessionId}/cancel, then create again (do not retry in a loop without handling 409). - If
statusispending, embedsessionUrlin an iframe (or redirect). - Wait for
biometric.session_*webhooks (or pollGET .../sessions/:id/POST .../syncif needed). - Use
statusand optionalrejectionCodeas the final biometric result.
Create Errors (POST /sessions)
Example
409 ACTIVE_SESSION_EXISTS (additive β existing clients that ignore extra fields are unchanged):
POST /sessions while a session is still open always returns this 409. Gu1 does not return 201 with the same pending session.
Prior Sessions and βCurrentβ Biometric
An entity may have many biometric sessions over time (approved, rejected, cancelled, etc.).
A previous approved session does not block creating a new one. Only a non-terminal latest session (
pending / in_progress) triggers 409 ACTIVE_SESSION_EXISTS.
hostedSessionId, Cancel, and Retries
hostedSessionId is the hosted capture session reference returned at create. Gu1 stores it uniquely and uses it for webhooks and sync.
Correct recovery:
hostedSessionId is seen again) applies only after cancel or other terminal outcomes β not while a session is still pending or in_progress.
Sandbox mock: hostedSessionId is prefixed with sandbox-mock-bio- and each mock create gets a new ID.
Embed in Your App
sessionUrl, or a compatible Web SDK initialized with the same URL.
Poll or Sync Status
GET /api/kyc/biometric/sessions/:idβ one session by IDGET /api/kyc/biometric/entities/:entityId/currentβ current session = most recent bycreatedAt(any status). Returns200withnullif none.GET /api/kyc/biometric/entities/by-tax-id/:taxId/currentβ same, resolved by tax IDGET /api/kyc/biometric/entities/by-external-id/:externalId/currentβ same, resolved by external IDGET /api/kyc/biometric/sessions?entityId=...β list; also acceptsentityTaxIdorentityExternalId(one at a time).currentSessionIdis the latestapprovedsession.POST /api/kyc/biometric/sessions/:id/syncβ refresh session state from Gu1 if webhooks are delayed.POST /api/kyc/biometric/sessions/:id/cancelβ manually cancelpendingorin_progresssessions (markscancelledin Gu1).
POST /sessions returns 409 ACTIVE_SESSION_EXISTS, the body includes activeSessionId so you can cancel without calling /current.
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:- Per-request
webhookUrlβ only if you sent it inPOST /sessions; fires on terminal status. - Organization webhooks β subscribe to
biometric.session_*events in Webhook configuration. See Biometric webhook events.
Comparison with Synchronous Biometric
For step-up authentication and login flows, prefer embedded sessions.
Sandbox Mock Sessions
In sandbox, when the entity has an approved KYC mock (testtaxId such as 99990001, or KYC with metadata.sandboxMock: true), POST /api/kyc/biometric/sessions can return an immediate mock result (approved or rejected) without hosted capture.
- Default:
99990001β biometric approved;99990011β biometric rejected (KYC still approved). - Override on any eligible entity:
"metadata": { "sandboxMockOutcome": "rejected" }. - Mock responses use
hostedSessionIdprefixed withsandbox-mock-bio-and may returnstatus: approvedorrejectedin the create response (not onlypending).