ID Verification (Document Front/Back)

Overview

ID Verification is a Gueno verification service that validates an identity document by sending the front image (required) and optionally the back image (for two-sided documents such as national IDs). The API returns Approved or Declined, plus extracted data (name, document number, date of birth, address, MRZ, etc.) and optional warnings. No hosted session 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): Compare two images (document portrait + selfie) to verify they are the same person; returns match + score.
ID Verification (POST /api/kyc/id-verification): Send document front (and optional back); get document validation, extracted data (MRZ, name, address, etc.), and Approved/Declined. Best when you already have document images and need extraction + validation only.

Prerequisites

Before using ID Verification:

ID Verification integration enabled: Your organization must have the ID Verification KYC integration activated (e.g. in Marketplace / Integrations).
Credentials configured: The API key for the ID Verification integration must be set in your organization’s KYC settings (configured by the Gueno administrator). This provider only requires the API key (no webhook secret for this endpoint).

ID Verification 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/id-verification

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 documentFront and (optional) documentBack.
As base64 strings: send the same field names with base64-encoded image strings (with or without data:image/...;base64, prefix).

documentFront is required: you must send either a file or a base64 string for it. If neither is provided, the API returns 400. documentBack is optional. For each image, if you send both a file and a base64 string, the file is used.

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

documentFront

file | string

required

Front image of the identity document. Send as a file part (recommended) or as a string (base64, with or without data:image/...;base64, prefix). Formats: JPEG, PNG, WebP, TIFF, PDF. Max 5MB.

documentBack

file | string

Back image of the document (optional; required for two-sided documents such as national IDs). Same as documentFront: file part or base64 string.

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.

performDocumentLiveness

boolean

Whether to perform document liveness (detect screen/copy). Default false. Send as string "true" or "false" in form.

minimumAge

number

Minimum age (1–120); users below are Declined. Optional. Send as string in form.

expirationDateNotDetectedAction

string

"NO_ACTION" or "DECLINE" when expiration date is not detected. Optional.

invalidMrzAction

string

"NO_ACTION" or "DECLINE" when MRZ is invalid or unreadable. Optional.

inconsistentDataAction

string

"NO_ACTION" or "DECLINE" when visual zone data does not match MRZ. Optional.

Response

Success Response (200 OK)

Field	Type	Description
`status`	string	`"approved"` \| `"declined"`.
`verificationId`	string (optional)	ID of the audit record in `id_verification_verifications` (for support and listing).
`requestId`	string (optional)	Internal request ID (for support).
`extractedData`	object (optional)	Extracted document data: `fullName`, `firstName`, `lastName`, `documentNumber`, `documentType`, `dateOfBirth`, `expirationDate`, `nationality`, `address`, `issuingState`, etc.
`warnings`	string[] (optional)	Warnings from the verification (e.g. document expired, inconsistent data).

Example:

{
  "status": "approved",
  "verificationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "requestId": "req_abc",
  "extractedData": {
    "fullName": "Elena Martínez Sánchez",
    "documentNumber": "YZA123456",
    "dateOfBirth": "1985-03-15",
    "expirationDate": "2022-08-21",
    "nationality": "ESP",
    "address": "Calle Mayor 10, 4B, Madrid"
  },
  "warnings": []
}

Example Request

const form = new FormData();
form.append('documentFront', documentFrontFile); // File object
if (documentBackFile) form.append('documentBack', documentBackFile);
form.append('entityId', '123e4567-e89b-12d3-a456-426614174000');

const response = await fetch('https://api.gu1.ai/api/kyc/id-verification', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: form,
});
const result = await response.json();
console.log('Status:', result.status, 'Data:', result.extractedData);

Error Responses

Responses use generic messages (no provider names). Common codes:

Code	HTTP	Meaning
`NOT_CONFIGURED`	403	ID Verification credentials (API key) not set in organization KYC settings.
`NOT_ENABLED`	403	ID Verification integration is not enabled for this organization.
`INVALID_REQUEST`	400	Content-Type not multipart/form-data, or missing/invalid document front (no file and no base64, or format/size).
`FORBIDDEN`	403	Verification could not be completed (e.g. credits).
`VERIFICATION_FAILED`	500	Generic failure; retry or try another document.

Audit and listing verifications

Every ID Verification request (success or failure) is stored in id_verification_verifications for audit and compliance. The response includes verificationId (the audit record ID) when persistence succeeds. All endpoints below are part of the Gueno API; no third-party provider names appear in responses or in this documentation.

Get a single verification

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

Returns one audit record by ID. Path: id — UUID of the verification (from the POST response verificationId or from the list). Response (200): Same shape as one item in the list: id, organizationId, entityId, status, requestId, vendorData, errorMessage, warnings, extractedData, createdAt, documentFrontStoragePath, documentBackStoragePath, storageProvider, etc.
404 if not found or not in your organization.

List audit records

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

Query parameters:

Parameter	Type	Description
`entityId`	string (UUID)	Optional. Filter by person entity.
`withoutEntity`	boolean	If `true`, only returns verifications with no associated entity (e.g. for the KYC page “ID Verification without entity” tab).
`status`	string	Optional. Filter by status (`approved`, `declined`, `failed`).
`limit`	number	Max items (default 50, max 100).
`offset`	number	Pagination offset.

Response: { "verifications": [ ... ], "pagination": { "limit", "offset", "total" } }. Each verification includes id, entityId, status, requestId, extractedData, warnings, errorMessage, createdAt, and storage paths when images were stored.

Get stored document images

If the verification has stored images (documentFrontStoragePath / documentBackStoragePath), you can stream them with:

GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id/document-front-image
GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id/document-back-image

Path: id — UUID of the verification. Response: Image bytes (e.g. Content-Type: image/jpeg). 404 if the verification does not exist or that side was not stored.

Coexistence with other KYC flows

Session flow creates a kyc_validations record and uses a hosted URL; the stored decision can include document, liveness, and face match from the live session.
Face Match compares document portrait + selfie and returns match + score; audit in face_match_verifications.
ID Verification validates the document (front/back), extracts data, and returns Approved/Declined; audit in id_verification_verifications. It does not create a kyc_validations record. Use it when you need document-only validation and extraction without a hosted session.

Getting Started

Use Cases

Webhooks

Person

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

ID Verification (Document Front/Back)

Overview

Prerequisites

Request

Endpoint

Content-Type

Headers

Form fields

Response

Success Response (200 OK)

Example Request

Error Responses

Audit and listing verifications

Get a single verification

List audit records

Get stored document images

Coexistence with other KYC flows

Next Steps

Face Match (Document + Selfie)

Create KYC Validation

Getting Started

Use Cases

Webhooks

Person

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Overview

​Prerequisites

​Request

​Endpoint

​Content-Type

​Headers

​Form fields

​Response

​Success Response (200 OK)

​Example Request

​Error Responses

​Audit and listing verifications

​Get a single verification

​List audit records

​Get stored document images

​Coexistence with other KYC flows

​Next Steps

Face Match (Document + Selfie)

Create KYC Validation

Overview

Prerequisites

Request

Endpoint

Content-Type

Headers

Form fields

Response

Success Response (200 OK)

Example Request

Error Responses

Audit and listing verifications

Get a single verification

List audit records

Get stored document images

Coexistence with other KYC flows

Next Steps