Face Match (Document + Selfie)

Verify that a selfie and a document photo belong to the same person via a single API call

POST /api/kyc/face-match

Face Match (Document + Selfie)

cURL

curl --request POST \
  --url http://api.gu1.ai/api/kyc/face-match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentImage": {},
  "selfieImage": {},
  "entityId": "<string>",
  "scoreThreshold": 123,
  "vendorData": "<string>"
}
'

Overview

Face Match is a Gueno 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:

1. Face Match integration enabled: Your organization must have the Face Match KYC integration activated (e.g. in Marketplace / Integrations).
2. Credentials configured: API key and webhook secret for the Face Match integration must be set in your organization’s KYC settings (configured by the Gueno administrator).
3. 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 Gueno service. All verification is performed by our infrastructure; no third-party provider names are exposed in API responses or error messages.

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):

1. As file parts: attach image files to the form fields documentImage and selfieImage.
2. 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.

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.

Example:

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

Example Request

Node.js (files)

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

Responses use generic messages (no provider names). Common 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	Generic failure; 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).

Next Steps

Create KYC Validation

Session-based verification with hosted URL

List Validations

List KYC validations by entity