ID Verification (Document Front/Back)

curl --request POST \
  --url http://api.gu1.ai/api/kyc/id-verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentFront": {},
  "documentBack": {},
  "entityId": "<string>",
  "vendorData": "<string>",
  "doubleCheckRenaper": true,
  "performDocumentLiveness": true,
  "minimumAge": 123,
  "expirationDateNotDetectedAction": "<string>",
  "invalidMrzAction": "<string>",
  "inconsistentDataAction": "<string>"
}
'

POST

api

kyc

id-verification

ID Verification (Document Front/Back)

curl --request POST \
  --url http://api.gu1.ai/api/kyc/id-verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentFront": {},
  "documentBack": {},
  "entityId": "<string>",
  "vendorData": "<string>",
  "doubleCheckRenaper": true,
  "performDocumentLiveness": true,
  "minimumAge": 123,
  "expirationDateNotDetectedAction": "<string>",
  "invalidMrzAction": "<string>",
  "inconsistentDataAction": "<string>"
}
'

Overview

ID Verification is a Gu1 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 Gu1 administrator). Only the API key is required (no webhook secret for this endpoint).

ID Verification is a Gu1 service. All verification is performed by Gu1 infrastructure.

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.

doubleCheckRenaper

boolean

When true, after document verification is approved, runs RENAPER data check (DNI + gender + trámite from OCR vs renaper/data). Requires org RENAPER credentials. Query overrides body.

doubleCheckRenaper

boolean

Same as query param doubleCheckRenaper.

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)	Normalized OCR and verification metadata from the Gu1 ID Verification service, persisted in audit. See extractedData fields below.
`warnings`	string[] (optional)	Array of risk codes from the verification (e.g. `DOCUMENT_EXPIRED`, `POSSIBLE_DUPLICATED_USER`). Use for display or i18n. See Warning risk codes for all possible values.
`debugProviderResponse`	object (optional)	Non-production only (Gu1 API `NODE_ENV=development`). Sanitized full verification response for debugging (image/base64 redacted). Do not rely on this in production integrations.
`doubleCheckRenaper`	boolean (optional)	`true` when RENAPER double-check was requested.
`responseDoubleChecks`	object (optional)	When `doubleCheckRenaper=true`: `renaper` with data/trámite result. See KYC validations RENAPER.

If RENAPER double-check fails after OCR approval, status becomes "declined" and RENAPER codes are added to warnings.

extractedData fields

The following fields are returned in extractedData and stored on id_verification_verifications.extracted_data (list/get audit endpoints). Empty fields are omitted. Identity and document (common):

Field	Type	Description
`providerStatus`	string	Document verification status detail (e.g. `Approved`, `Declined`). Top-level `status` is normalized to `approved` / `declined`.
`fullName`, `firstName`, `lastName`	string	Name from OCR.
`firstSurname`, `secondSurname`	string	When returned in supplementary fields (e.g. some LATAM IDs).
`documentNumber`, `personalNumber`	string	Document number and personal/national ID number when present.
`documentType`	string	e.g. `Driver's License`, `National ID`.
`taxNumber`	string	Tax ID when present (e.g. CPF in supplementary extraction).
`dateOfBirth`, `age`	string / number	Date of birth and computed age.
`expirationDate`, `dateOfIssue`, `firstIssueDate`	string	Document dates (ISO `YYYY-MM-DD` when provided).
`nationality`, `gender`	string	ISO country code and gender code when present.
`placeOfBirth`, `maritalStatus`	string	When returned by OCR.
`address`, `formattedAddress`	string	Address lines when present.
`issuingState`, `issuingStateName`	string	Issuing jurisdiction (e.g. `BRA`, `Brazil`).

Supplementary (nested; may be empty):

Field	Type	Description
`extraFields`	object	Document keys not promoted to top-level fields (e.g. license category, regional codes). Extension bucket for future OCR keys.
`warningMeta`	object	Metadata from warnings, e.g. `duplicatedSessionId`, `duplicatedSessionNumber`, `duplicatedApiService` when `POSSIBLE_DUPLICATED_USER` is returned.
`frontImageQualityScore`, `backImageQualityScore`	object	OCR quality scores (focus, brightness, overall, etc.) when available.
`mrz`	object	Parsed MRZ fields when non-empty.
`parsedAddress`	object	Structured address when returned.
`barcodes`	array	Barcode reads when returned.

Promoted fields vs. extension bucket

Common keys (taxNumber, firstSurname, secondSurname, firstIssueDate, etc.) are promoted to the top level of extractedData when OCR returns them.
Any other document keys stay in extractedData.extraFields (same object on POST and audit list/get).

Not included in API responses or audit JSON

Temporary external image URLs from the verification pipeline — use stored document images (document-front-image / document-back-image) for images Gu1 saved from your upload.
Full raw verification response body (not exposed in production APIs).

Example (approved):

{
  "status": "approved",
  "verificationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "requestId": "req_abc",
  "extractedData": {
    "providerStatus": "Approved",
    "fullName": "Elena Martínez Sánchez",
    "firstName": "Elena",
    "lastName": "Martínez Sánchez",
    "documentNumber": "YZA123456",
    "documentType": "National ID",
    "dateOfBirth": "1985-03-15",
    "expirationDate": "2030-08-21",
    "nationality": "ESP",
    "address": "Calle Mayor 10, 4B, Madrid",
    "issuingState": "ESP",
    "issuingStateName": "Spain",
    "personalNumber": "AAA123456",
    "dateOfIssue": "2020-01-10",
    "gender": "F",
    "parsedAddress": {
      "street": "Calle Mayor",
      "city": "Madrid",
      "country": "ESP",
      "formatted_address": "Calle Mayor 10, 4B, Madrid"
    },
    "frontImageQualityScore": {
      "overall_score": 97.5,
      "focus_score": 100,
      "is_document_fully_visible": true
    },
    "backImageQualityScore": {
      "overall_score": 96.0,
      "focus_score": 99
    }
  },
  "warnings": []
}

Example (declined with warnings and LATAM extra fields):

{
  "status": "declined",
  "verificationId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "requestId": "4e2bf9fb-d75b-4b26-9362-e51436cfe1eb",
  "extractedData": {
    "providerStatus": "Declined",
    "fullName": "Breno Henrique Ferreira Silva",
    "firstName": "Breno Henrique",
    "lastName": "Ferreira Silva",
    "firstSurname": "Ferreira",
    "secondSurname": "Silva",
    "documentNumber": "08585626509",
    "personalNumber": "2156732124SSPBA",
    "documentType": "Driver's License",
    "taxNumber": "10584158599",
    "dateOfBirth": "2004-08-29",
    "age": 21,
    "expirationDate": "2025-03-07",
    "dateOfIssue": "2024-03-08",
    "firstIssueDate": "2024-03-08",
    "nationality": "BRA",
    "gender": "U",
    "placeOfBirth": "Barreiras/Ba",
    "maritalStatus": "UNKNOWN",
    "issuingState": "BRA",
    "issuingStateName": "Brazil",
    "warningMeta": {
      "duplicatedSessionId": "a4bfeef8-6d6e-4e9b-8fcb-44950912b2b4",
      "duplicatedSessionNumber": 2834,
      "duplicatedApiService": "ID_VERIFICATION"
    },
    "frontImageQualityScore": {
      "overall_score": 98.2,
      "focus_score": 100,
      "brightness_score": 94,
      "is_document_fully_visible": true
    },
    "formattedAddress": null,
    "extraFields": {
      "license_category": "AB",
      "restrictions": "01"
    },
    "mrz": {
      "line1": "IDBRA085856265<<<<<<<<<<<<<<<",
      "line2": "0408299M2503077BRA<<<<<<<<<<<6",
      "line3": "SILVA<<BRENO<HENRIQUE<FERREIRA"
    },
    "parsedAddress": {},
    "backImageQualityScore": {
      "overall_score": 97.1,
      "focus_score": 100
    },
    "barcodes": []
  },
  "warnings": ["DOCUMENT_EXPIRED", "POSSIBLE_DUPLICATED_USER"]
}

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

Common error 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	Verification could not be completed; 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 Gu1 API.

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.

Next Steps

Face Match (Document + Selfie)

Compare document photo and selfie

Create KYC Validation

Session-based verification with hosted URL

Biometric Check Get ID Verification (List & Single)

⌘I

Documentation Index

​Overview

​Prerequisites

​Request

​Endpoint

​Content-Type

​Headers

​Form Fields

​Response

​Success Response (200 OK)

​extractedData fields

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

extractedData fields

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