Face Match (Document + Selfie)

Overview

Face Match is a Gu1 verification service that compares two images: a selfie (current photo of the person) and a document reference image (e.g. the portrait from an ID). The API returns whether the faces match (same person) and a similarity score. No hosted session or real-time liveness is involved—you send the images and get the result in one call.

When to use which

Session-based KYC (POST /api/kyc/validations): Full flow with hosted URL, live selfie, liveness, and document capture. Best for onboarding and regulated flows.
Face Match (POST /api/kyc/face-match): You send two images (as files or base64); you get back match + score. Best for validating document + selfie you already have (e.g. from your own app).

Prerequisites

Before using Face Match:

Face Match integration enabled: Your organization must have the Face Match KYC integration activated (e.g. in Marketplace / Integrations).
Credentials configured: API key and webhook secret for the Face Match integration must be set in your organization’s KYC settings (configured by the Gu1 administrator).
Threshold (optional): The minimum score required to approve (0–100) is configured in Organization Settings → KYC (Face Match card). If not set, the default is 30. Only your organization’s admins can change this value.

Face Match is a Gu1 service. All verification is performed by Gu1 infrastructure.

Request

Endpoint

POST https://api.gu1.ai/api/kyc/face-match

Content-Type

Only multipart/form-data is accepted. You can send images in either of two ways (or mix):

As file parts: attach image files to the form fields documentImage and selfieImage.
As base64 strings: send the same field names with base64-encoded image strings (with or without data:image/...;base64, prefix).

If a required image is missing (no file and no base64 for that field), the API returns 400. For each image, if you send both a file and a base64 string, the file takes precedence.

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data; boundary=----...

Do not set Content-Type manually when using FormData; the client will set it with the correct boundary. If your account uses organization scoping, include:

X-Organization-Id: YOUR_ORGANIZATION_ID

Form Fields

documentImage

file | string

required

Reference image (e.g. portrait from ID document). Send as a file part (recommended) or as a string (base64, with or without data:image/...;base64, prefix). Formats: JPEG, PNG, WebP, TIFF. Max 5MB.

selfieImage

file | string

required

Selfie image. Same as documentImage: file part or base64 string. Required.

entityId

string

Optional UUID of the person entity to associate with this check. Used for audit and for listing verifications by entity.

scoreThreshold

number

Optional. Score threshold 0–100; results below are declined. If omitted, the organization’s configured threshold (or default 30) is used.

vendorData

string

Optional reference (e.g. your user ID) for tracking. Stored with the audit record.

doubleCheckRenaper

boolean

When true, after Gu1 face match approves, runs RENAPER biometric (validate-dni with the selfie) and data (renaper/data: DNI + trámite) checks. Requires org RENAPER credentials and active Marketplace integrations: ar_renaper_data_enrichment and ar_renaper_validate_dni_enrichment. Query overrides body if both are sent.

doubleCheckRenaper

boolean

Same as query param doubleCheckRenaper.

documentNumber

string

DNI for RENAPER when doubleCheckRenaper=true. Optional if entityId resolves taxId or person.idNumber.

gender

string

Gender for RENAPER (M, F, male, female). Required for double-check unless resolved from linked entity.

personalNumber

string

required

Número de trámite for RENAPER data check. Required when doubleCheckRenaper=true.

The minimum score (threshold) can be sent in the form; if not sent, it is read from your organization’s KYC configuration. The response includes the threshold that was used for the call.

Response

Success Response (200 OK)

Field	Type	Description
`match`	boolean	Whether the faces were considered a match (score ≥ threshold).
`score`	number	Similarity score 0–100.
`status`	string	`"approved"` \| `"declined"` \| `"in_review"`.
`verificationId`	string	ID of the audit record in `face_match_verifications` (for support and listing).
`scoreDeclineThreshold`	number	The threshold (0–100) that was used for this verification (from org settings).
`requestId`	string (optional)	Internal request ID (for support).
`warnings`	string[] (optional)	Array of risk codes from the verification (e.g. `LOW_FACE_MATCH_SIMILARITY`, `NO_REFERENCE_IMAGE`). See Warning risk codes for all possible values.
`doubleCheckRenaper`	boolean (optional)	`true` when RENAPER double-check was requested.
`responseDoubleChecks`	object (optional)	When `doubleCheckRenaper=true`: `renaper` (data/trámite) and `renaperBiometric` (ABIS match). Same shape as KYC validations RENAPER.

If RENAPER double-check fails after provider approval, match becomes false, status becomes "declined", and RENAPER codes (e.g. RENAPER_BIOMETRIC_NOT_MATCH) are added to warnings. Allow 60+ seconds HTTP timeout when using double-check (biometric polling). Example:

{
  "match": true,
  "score": 85.5,
  "status": "approved",
  "verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scoreDeclineThreshold": 30,
  "requestId": "req_xyz",
  "warnings": []
}

Example Request

const form = new FormData();
form.append('documentImage', documentFile); // File object
form.append('selfieImage', selfieFile);
form.append('entityId', '123e4567-e89b-12d3-a456-426614174000');

const response = await fetch('https://api.gu1.ai/api/kyc/face-match', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: form,
});
const result = await response.json();
console.log('Match:', result.match, 'Score:', result.score);

Error Responses

Common error codes:

Code	HTTP	Meaning
`NOT_CONFIGURED`	403	Face Match credentials not set in organization KYC settings.
`NOT_ENABLED`	403	Face Match integration is not enabled for this organization.
`INVALID_REQUEST`	400	Content-Type not multipart/form-data, or missing/invalid images (e.g. no file and no base64 for a required field, format/size).
`UNAUTHORIZED`	401	Invalid or missing API/verification credentials.
`QUOTA_EXCEEDED`	403	Verification could not be completed (e.g. quota/credits).
`SERVICE_UNAVAILABLE`	503	Verification service temporarily unavailable.
`VERIFICATION_FAILED`	500	Verification could not be completed; retry or try other images.

Audit and Listing Verifications

Every Face Match request (success or failure) is stored in face_match_verifications for audit and compliance. The response includes verificationId (the audit record ID). Each stored record also saves the threshold that was used at the time of the call (so you can show it in history even if the org threshold changes later).

List Audit Records

GET https://api.gu1.ai/api/kyc/face-match/verifications?entityId={entityId}&limit=50&offset=0

Query parameters:

Parameter	Type	Description
`entityId`	string (UUID)	Optional. Filter by person entity.
`status`	string	Optional. Filter by status (`approved`, `declined`, `in_review`, `failed`).
`limit`	number	Max items (default 50, max 100).
`offset`	number	Pagination offset.

Response: { "verifications": [ ... ], "scoreDeclineThreshold": 30, "pagination": { "limit", "offset", "total" } }. Each verification includes id, entityId, status, match, score, threshold (the value used for that run), createdAt, and optional image paths for audit.

Get Verification by ID

Retrieve a single Face Match audit record by its verificationId (returned in the POST response or in the list).

GET https://api.gu1.ai/api/kyc/face-match/verifications/:id

Path parameter: id — UUID of the verification (same as verificationId from the POST or list). Response (200): One verification object with the same fields as each item in the list: id, organizationId, entityId, status, match, score, requestId, vendorData, errorMessage, triggeredByUserId, createdAt, documentStoragePath, selfieStoragePath, storageProvider, threshold. Errors: 404 NOT_FOUND if the ID does not exist or belongs to another organization; 401 UNAUTHORIZED if not authenticated.

Coexistence with Session-Based KYC

Session flow creates a kyc_validations record, sends the user to a hosted URL, and updates status via webhooks. The stored decision includes document, liveness, and face match from the live session.
Face Match creates an audit record in face_match_verifications and returns the result in the same request. It does not create a kyc_validations record. Use it when you need a one-off check (e.g. “are these two images the same person?”) without a hosted session.
Both use the same organization KYC configuration. The threshold for Face Match is set in Organization Settings → KYC (Face Match card).

Face Match (Document + Selfie)

Overview

Prerequisites

Request

Endpoint

Content-Type

Headers

Form Fields

Response

Success Response (200 OK)

Example Request

Error Responses

Audit and Listing Verifications

List Audit Records

Get Verification by ID

Coexistence with Session-Based KYC

Next Steps

Create KYC Validation

List Validations

Documentation Index

​Overview

​Prerequisites

​Request

​Endpoint

​Content-Type

​Headers

​Form Fields

​Response

​Success Response (200 OK)

​Example Request

​Error Responses

​Audit and Listing Verifications

​List Audit Records

​Get Verification by ID

​Coexistence with Session-Based KYC

​Next Steps

Create KYC Validation

List Validations

Overview

Prerequisites

Request

Endpoint

Content-Type

Headers

Form Fields

Response

Success Response (200 OK)

Example Request

Error Responses

Audit and Listing Verifications

List Audit Records

Get Verification by ID

Coexistence with Session-Based KYC

Next Steps