Skip to main content
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.
The Biometric service is a Gu1 verification that checks whether a face image corresponds to a person who has already completed an approved KYC validation in your organization. You send a single face image and the entity to check (by 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:
  1. 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).
  2. 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.
If these credentials are not set or the integration is not enabled, the API returns 403 (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

Accepts multipart/form-data or application/json. Multipart β€” send the face image in either way (same as Face Match / ID Verification):
  1. As a file part: field userImage or user_image (recommended).
  2. As a base64 string: same field names with a base64-encoded image (with or without data:image/...;base64, prefix).
If the image is missing (no file and no base64 string), the API returns 400. JSON β€” send 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

or, for multipart:
The organization is determined from your authentication context; you do not need to send X-Organization-Id.

Body Parameters

user_image
file | string
required
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.
entityId
string
UUID of the person entity in Gu1. At least one of entityId, entityExternalId, or entityTaxId is required.
entityExternalId
string
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.
externalEntityId
string
Deprecated alias for entityExternalId. Still accepted on POST /api/kyc/biometric for backward compatibility. Prefer entityExternalId in new integrations.
entityTaxId
string
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.
Both use the same organization credentials for session-based KYC validation. If those credentials are not configured, the Biometric endpoint cannot run.

Next Steps

Create KYC Validation

Start a session-based verification

Face Match (Document + Selfie)

Compare two images in one call