Skip to main content
POST
http://api.gu1.ai
/
api
/
kyc
/
face-match
Face Match (Document + Selfie)
curl --request POST \
  --url http://api.gu1.ai/api/kyc/face-match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentImage": "<string>",
  "selfieImage": "<string>",
  "entityId": "<string>",
  "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 base64 images; 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

​
Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}
If your account uses organization scoping, include: 
X-Organization-Id: YOUR_ORGANIZATION_ID

​
Body Parameters

​
documentImage
string
required
Reference image (e.g. portrait from ID document) as Base64. With or without data:image/...;base64, prefix. Formats: JPEG, PNG, WebP, TIFF. Max 5MB per image.
​
selfieImage
string
required
Selfie image as Base64. Same format and size limits as documentImage.
​
entityId
string
Optional UUID of the person entity to associate with this check. Used for audit and for listing verifications by entity.
​
vendorData
string
Optional reference (e.g. your user ID) for tracking. Stored with the audit record.
The minimum score (threshold) used to decide match vs no match is not sent in the request. It is read from your organization’s KYC configuration (Organization Settings → KYC → Face Match). The response includes the threshold that was used for the call.

​
Response

​
Success Response (200 OK)

FieldTypeDescription
matchbooleanWhether the faces were considered a match (score ≥ threshold).
scorenumberSimilarity score 0–100.
statusstring"approved" | "declined" | "in_review".
verificationIdstringID of the audit record in face_match_verifications (for support and listing).
scoreDeclineThresholdnumberThe threshold (0–100) that was used for this verification (from org settings).
requestIdstring (optional)Internal request ID (for support).
warningsstring[] (optional)Warnings from the verification.
Example: 
{
  "match": true,
  "score": 85.5,
  "status": "approved",
  "verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scoreDeclineThreshold": 30,
  "requestId": "req_xyz",
  "warnings": []
}

​
Example Request

const response = await fetch('https://api.gu1.ai/api/kyc/face-match', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    documentImage: 'data:image/jpeg;base64,/9j/4AAQ...',
    selfieImage: 'data:image/jpeg;base64,/9j/4AAQ...',
    entityId: '123e4567-e89b-12d3-a456-426614174000',
  }),
});

const result = await response.json();
console.log('Match:', result.match, 'Score:', result.score);

​
Error Responses

Responses use generic messages (no provider names). Common codes:
CodeHTTPMeaning
NOT_CONFIGURED403Face Match credentials not set in organization KYC settings.
NOT_ENABLED403Face Match integration is not enabled for this organization.
INVALID_REQUEST400Invalid or missing images (e.g. format/size).
UNAUTHORIZED401Invalid or missing API/verification credentials.
QUOTA_EXCEEDED403Verification could not be completed (e.g. quota/credits).
SERVICE_UNAVAILABLE503Verification service temporarily unavailable.
VERIFICATION_FAILED500Generic 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:
ParameterTypeDescription
entityIdstring (UUID)Optional. Filter by person entity.
statusstringOptional. Filter by status (approved, declined, in_review, failed).
limitnumberMax items (default 50, max 100).
offsetnumberPagination 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