Skip to main content
POST
/
api
/
kyc
/
biometric
Biometric Check
curl --request POST \
  --url http://api.gu1.ai/api/kyc/biometric \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_image": "<string>",
  "entityId": "<string>",
  "externalEntityId": "<string>"
}
'

​
Overview

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 or externalEntityId). 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

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

​
Content-Type

You can send the request in either format:
  • multipart/form-data: use form fields userImage or user_image (file or base64) and optional entityId, externalEntityId.
  • application/json: body with user_image (base64 string) and optional entityId, externalEntityId.
You must provide at least one of entityId or externalEntityId so the API knows which entity to check against.

​
Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
or, for multipart: 
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data; boundary=----...
The organization is determined from your authentication context; you do not need to send X-Organization-Id.

​
Body parameters

​
user_image
string
required
Face image as base64 (with or without data:image/...;base64, prefix). For multipart, use the field name userImage or user_image and send a file or a base64 string. Formats: JPEG, PNG, WebP, TIFF. Max 5MB.
​
entityId
string
UUID of the person entity in Gu1. Either entityId or externalEntityId is required.
​
externalEntityId
string
Your own identifier for the entity (external ID). If you do not send entityId, the API resolves the entity by organization + externalId. Either entityId or externalEntityId is required.

​
Response

​
Success (200 OK)

FieldTypeDescription
matchbooleantrue if the face matched at least one KYC validation that is approved in your account for this entity (see note below).
approvedSessionIdsstring[]Session IDs from the verification service that were considered approved matches.
matchedKycValidationIdsstring[]IDs of the KYC validations in your account that correspond to those sessions and have status approved in our database.
A match is only returned when the validation exists in our DB with status approved. If a session was approved by the verification service but we later rejected it (e.g. due to a RENAPER mismatch), it will appear as rejected in our database and will not be counted as a match. | faceSearch | object | Summary: status, totalMatches, approvedMatchesCount, requestId (for support). | Example: 
{
  "match": true,
  "approvedSessionIds": ["session-abc-123"],
  "matchedKycValidationIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "faceSearch": {
    "status": "Approved",
    "totalMatches": 1,
    "approvedMatchesCount": 1,
    "requestId": "req_xyz"
  }
}

​
Example request

const response = await fetch('https://api.gu1.ai/api/kyc/biometric', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_image: 'data:image/jpeg;base64,/9j/4AAQ...',
    entityId: '550e8400-e29b-41d4-a716-446655440000',
  }),
});
const result = await response.json();
console.log('Match:', result.match, 'KYC validations:', result.matchedKycValidationIds);

​
Error Responses

CodeHTTPMeaning
NOT_CONFIGURED403Session-based KYC validation credentials are not set in organization KYC settings.
NOT_ENABLED403Session-based KYC validation integration is not enabled for this organization.
INVALID_REQUEST400Missing or invalid body (e.g. missing user_image, or neither entityId nor externalEntityId).
NOT_FOUND404No entity found for the given externalEntityId in this organization.
UNAUTHORIZED401Invalid or missing authentication.
VERIFICATION_FAILED500Verification could not be completed; retry or contact support.

​
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