Biometric Check
Biometric
Biometric Check
Validate a face image against previously approved KYC sessions β in the gu1 KYC API for identity verification flows, with examples for biometric use cases.
POST
Biometric Check
Overview
For step-up authentication with hosted liveness capture (iframe), use Embedded Biometric Session (
POST /api/kyc/biometric/sessions) instead of this synchronous endpoint. This page documents the server-side image upload check.entityId, entityExternalId, or entityTaxId). The API compares that face against the biometric data stored in previous approved session-based validations for that entity. If the face matches one of those approved sessions, the response indicates a match and returns the related KYC validation IDs.
How it worksThe service looks up approved KYC sessions (created via session-based validation) for the given entity. It compares the face you send with the biometric information already stored from those approved sessions. No new hosted session is startedβthis is a one-off check against existing data.
Prerequisites
For this endpoint to work, your organization must have session-based KYC validation set up:- KYC Validation integration enabled: The integration used for session-based validation (e.g. βGu1 KYCβ / validation by session) must be enabled for your organization (e.g. in Marketplace / Integrations).
- Credentials configured: The API key (and webhook secret) for that session validation integration must be set in your organizationβs KYC settings. The Biometric endpoint uses the same credentials as session-based validation to perform the check.
NOT_ENABLED or NOT_CONFIGURED).
The Biometric service is a Gu1 service. All verification runs on our infrastructure; no third-party provider names are exposed in responses or errors.
Request
Endpoint
Content-Type
Acceptsmultipart/form-data or application/json.
Multipart β send the face image in either way (same as Face Match / ID Verification):
- As a file part: field
userImageoruser_image(recommended). - As a base64 string: same field names with a base64-encoded image (with or without
data:image/...;base64,prefix).
user_image or userImage as a base64/data URL string, or an http(s) URL to fetch the image server-side. Entity identifiers: entityId, entityExternalId, and/or entityTaxId.
You must provide at least one of entityId, entityExternalId, or entityTaxId so the API knows which entity to check against.
Headers
X-Organization-Id.
Body Parameters
Face image. Multipart: field
userImage or user_image as a file part or base64 string (with or without data:image/...;base64, prefix). JSON: user_image or userImage as base64, data URL, or http(s) URL. Formats: JPEG, PNG, WebP, TIFF. Max 5MB.UUID of the person entity in Gu1. At least one of
entityId, entityExternalId, or entityTaxId is required.Your own identifier for the entity (external ID). If you do not send
entityId, the API resolves the entity by organization + externalId. At least one entity identifier is required.Deprecated alias for
entityExternalId. Still accepted on POST /api/kyc/biometric for backward compatibility. Prefer entityExternalId in new integrations.Tax ID of the entity (CUIT, CPF, RFC, etc.). If you do not send
entityId or entityExternalId, the API resolves the entity by organization + normalized tax_id (ignores formatting characters such as dashes and dots). At least one entity identifier is required.Response
Success (200 OK)
Example:
Example Request
Error Responses
Relation to Session-Based KYC
- Session-based validation (
POST /api/kyc/validations): Creates a KYC session, gives the user a hosted URL, and stores the result (including biometric data) when they complete the flow. Those sessions are what the Biometric endpoint checks against. - Biometric (
POST /api/kyc/biometric): Sends one face image and checks if it matches any already approved session for that entity. Use it when you need to re-verify the same person (e.g. at login or for a new action) without starting a new session.
Next Steps
Create KYC Validation
Start a session-based verification
Face Match (Document + Selfie)
Compare two images in one call