KYC Warning Risk Codes

Overview

The ID Verification, Face Match, and Liveness APIs return a warnings field when the verification service signals non-blocking issues or risk flags. Session-based KYC (POST /api/kyc/validations, GET /api/kyc/validations/:id) stores a top-level warnings array on the validation record by merging risk codes from document verification, liveness, face match, and AML screening, and may add Gu1-internal codes (e.g. blocklist or sandbox). Clients can use these codes for:

Display: Map each code to a human-readable message (e.g. your own i18n, or the descriptions below — the gu1 dashboard resolves labels in the same order as keys under warningRisks and rejectionReasonCodes in the product locale files).
Logic: Branch on specific codes (e.g. DOCUMENT_EXPIRED vs POSSIBLE_DUPLICATED_USER), or pass allowed codes in omitWarnings when creating a validation.

The codes are per service for standalone APIs; the session validation record uses the union of services plus internal codes. Below are the documented values.

If the service returns a code not listed here, you may still receive it in warnings. Treat unknown codes as generic warnings and display the code or a fallback message.

Session-Based KYC Validation

For GET /api/kyc/validations/:id (and list endpoints), the validation’s top-level warnings array contains risk code strings collected from:

Document (ID) verification step
Liveness step
Face match step
AML screening objects in the session decision
Device & IP analysis objects in the session decision (ip_analyses[] / ip_analysis)

Additional codes may be appended by Gu1 rules (e.g. organization blocklist enforcement). Optional omitWarnings on POST /api/kyc/validations references the same code strings documented in the tables below.

ID Verification

Returned in POST /api/kyc/id-verification and GET /api/kyc/id-verification/verifications/:id in the warnings array. The same codes can appear on session validations from the document step.

Code	Description
`ID_DOCUMENT_IN_BLOCKLIST`	The document has been identified as matching an entry in your document blocklist (e.g. previously marked as fraudulent, stolen, or otherwise problematic).
`BARCODE_NOT_DETECTED`	The system could not find or read the barcode on the document; may be due to poor image quality or unsupported document type.
`BARCODE_VALIDATION_FAILED`	The barcode could not be validated against other data on the document.
`QR_NOT_DETECTED`	The system could not find or read the QR code on the document.
`QR_VALIDATION_FAILED`	The QR code could not be validated against other data on the document.
`MRZ_NOT_DETECTED`	The Machine Readable Zone (MRZ) could not be found or read.
`MINIMUM_AGE_NOT_MET`	The user’s age is below the minimum required for the application.
`DATA_INCONSISTENT`	OCR data and NFC chip data do not match; possible document tampering or data inconsistency.
`COULD_NOT_RECOGNIZE_DOCUMENT`	The system could not confirm the authenticity or validity of the document.
`PORTRAIT_IMAGE_NOT_DETECTED`	The portrait image on the document could not be identified or processed.
`IMAGE_TOO_BLURRY`	The document image is too blurry; recapture with better focus.
`IMAGE_TOO_DARK`	The document image is too dark; improve lighting when capturing.
`IMAGE_TOO_BRIGHT`	The document image is too bright or overexposed; avoid direct light when capturing.
`DOCUMENT_NUMBER_NOT_DETECTED`	The document number could not be located or read.
`DATE_OF_BIRTH_NOT_DETECTED`	The date of birth on the document could not be identified or processed.
`EXPIRATION_DATE_NOT_DETECTED`	The expiration date on the document could not be identified or processed.
`NAME_NOT_DETECTED`	The first name and/or last name on the document could not be identified or processed.
`MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`	Differences between MRZ and OCR-extracted data; possible document alteration.
`MRZ_VALIDATION_FAILED`	The MRZ does not meet the expected format or contains invalid data.
`INVALID_DATE`	One or more dates on the document are not valid or do not match expected formats.
`DOCUMENT_EXPIRED`	The document’s expiration date has passed.
`DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`	The type of document provided is not accepted for the current verification process.
`DOCUMENT_SIDES_MISMATCH`	The sides of the document do not match the expected format or contain invalid data.
`COULD_NOT_DETECT_DOCUMENT_TYPE`	The system could not determine the type of document submitted.
`DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`	The name on this document does not match the name on other documents previously verified for this user.
`POSSIBLE_DUPLICATED_USER`	The system identified a potential duplicate user with previously approved documents from another session.
`LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY`	The face captured during document scanning does not sufficiently match the portrait on the document.
`FULL_NAME_MISMATCH_WITH_PROVIDED`	The provided full name does not match the data extracted from the document.
`DOB_MISMATCH_WITH_PROVIDED`	The provided date of birth does not match the date extracted from the document.
`GENDER_MISMATCH_WITH_PROVIDED`	The provided gender does not match the gender extracted from the document.
`COUNTRY_MISMATCH_WITH_PROVIDED`	The provided country does not match the country extracted from the document.
`NATIONALITY_MISMATCH_WITH_PROVIDED`	The provided nationality does not match the nationality extracted from the document.
`IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED`	The provided identification number does not match the document number, personal number, or tax number extracted from the document.
`SCREEN_CAPTURE_DETECTED`	The submitted document appears to be a screen capture or photo of a document on a screen rather than a physical document.
`PRINTED_COPY_DETECTED`	The submitted document appears to be a printed copy rather than an original official document.
`PORTRAIT_MANIPULATION_DETECTED`	Potential manipulation of the portrait area of the document was detected.
`UNPARSED_ADDRESS`	The address on the document could not be parsed or geolocated.
`DOCUMENT_NUMBER_FORMAT_MISMATCH`	The document number does not match the expected format for this type of document.
`PERSONAL_NUMBER_FORMAT_MISMATCH`	The personal number does not match the expected format for this type of document.
`ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS`	Data extracted from multiple ID verification documents in this session do not match (e.g. name or date of birth).
`GUENO_KYC_ORG_BLOCKLIST_HIT`	Automatic rejection path: a value from this validation matched an organization KYC blocklist (aggregate signal).
`GUENO_KYC_ORG_BLOCKLIST_IP`	Organization KYC blocklist: the session IP address matched an enforcement list.
`GUENO_KYC_ORG_BLOCKLIST_DOCUMENT`	Organization KYC blocklist: the document number matched an enforcement list.
`GUENO_KYC_ORG_BLOCKLIST_PERSONAL`	Organization KYC blocklist: the personal / transaction number matched an enforcement list.
`GUENO_KYC_ORG_MINIMUM_AGE_NOT_MET`	Organization minimum-age policy (KYC organization settings): the extracted date of birth implies fewer full years than the configured threshold; the validation is set to rejected even if OCR validated identity. If no parsable date of birth is present, this rule does not apply.

Face Match

Returned in POST /api/kyc/face-match and GET /api/kyc/face-match/verifications/:id in the warnings array.

Code	Description
`LOW_FACE_MATCH_SIMILARITY`	The facial features of the provided image do not closely match the reference image; potential identity mismatch.
`NO_REFERENCE_IMAGE`	A reference image or face image for facial comparison is missing; the face matching process could not be completed.

Liveness (Session-Based KYC)

Returned in session-based KYC validation responses (e.g. current validation, list validations) when liveness checks are performed. The warnings array in the validation payload may contain these codes.

Code	Description
`FACE_IN_BLOCKLIST`	The face matches an entry in your face blocklist (e.g. previously blocklisted individual).
`POSSIBLE_FACE_IN_BLOCKLIST`	The system identified a possible face in the blocklist; the face is not allowed to be verified.
`LOW_LIVENESS_SCORE`	The liveness check resulted in a low score; possible non-live facial representation or poor-quality biometric data.
`NO_FACE_DETECTED`	The system could not identify a face during the liveness check.
`LIVENESS_FACE_ATTACK`	The system detected a potential attempt to bypass the liveness check.
`DUPLICATED_FACE`	The system identified a duplicated face from another approved session.
`POSSIBLE_DUPLICATED_FACE`	This face may match another user already approved in the system.
`MULTIPLE_FACES_DETECTED`	Multiple faces were detected; the system uses the largest face for verification. (Passive Liveness only)
`LOW_FACE_QUALITY`	The facial image quality is below the acceptable threshold. (Passive Liveness only)
`LOW_FACE_LUMINANCE`	The facial image is too dark. (Passive Liveness only)
`HIGH_FACE_LUMINANCE`	The facial image is too bright or overexposed. (Passive Liveness only)

AML (Session-Based KYC)

When AML screening runs inside a session, risk codes from screening warnings are merged into the validation’s top-level warnings array.

Code	Description
`POSSIBLE_MATCH_FOUND`	AML screening identified potential matches with watchlists or high-risk databases; may require review.
`COULD_NOT_PERFORM_AML_SCREENING`	AML screening could not be completed with the data available (e.g. missing fields required for screening).

Device & IP Analysis (Session-Based KYC)

When device and IP analysis runs inside a session, risk codes from ip_analyses[].warnings[] (or legacy ip_analysis.warnings) are merged into the validation’s top-level warnings array. These codes follow the provider’s Device & IP analysis warning taxonomy.

Code	Description
`PRIVATE_NETWORK_DETECTED`	The session was opened via VPN, proxy, or Tor exit node.
`COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP`	The country on the identity document differs from the country derived from the IP address.
`EXPECTED_IP_ADDRESS_MISMATCH`	The live IP address differs from the expected IP provided at session creation.
`IP_ADDRESS_IN_BLOCKLIST`	The session IP address matches an entry in the provider IP blocklist (forces decline at the provider).
`DEVICE_FINGERPRINT_IN_BLOCKLIST`	The device fingerprint matches an entry in the provider device blocklist (forces decline at the provider).
`DUPLICATED_IP_ADDRESS`	The same IP address was used in another session with a different user identifier (`vendor_data`).
`DUPLICATED_DEVICE_FINGERPRINT`	The same persistent device fingerprint was reused across sessions with different user identifiers.
`DEVICE_RECOVERED_HIGH_CONFIDENCE`	High-confidence device recovery matched this session to a previously seen device after the persistent ID changed (e.g. incognito, storage reset, or app reinstall).

Internal (Gu1)

These codes may be added by Gu1 logic (entity vs OCR checks, name policy, sandbox mocks, etc.) and appear in the session validation warnings array where applicable.

Code	Description
`GUENO_DOCUMENT_NUMBER_MISMATCH`	The document number from verification does not match the entity document at check time.
`GUENO_PERSONAL_NUMBER_MISMATCH`	Document/personal number checks against the entity did not align as required.
`GUENO_KYC_NAME_SIMILARITY_BELOW_MIN`	Entity name similarity to the document-derived name is below the organization minimum.
`GUENO_CROSS_ENTITY_DUPLICATED`	Gu1 confirmed the face/session duplicate references another entity in the same organization (`metadata.kycCrossEntityDuplicates.matches`). If OCR mapped `approved`, Gu1 sets status to `in_review` for manual review. Non-omittable: cannot appear in `omitWarnings` and blocks omit auto-approve. Matches against another entity with the same tax ID (normalized) as the evaluated entity do not count as cross-entity.
`SANDBOX_KYC_REJECTED_DEFAULT`	Sandbox test outcome: validation rejected when the tax ID matched the sandbox test list.

Cross-entity duplicates: Provider codes such as DUPLICATED_FACE or POSSIBLE_DUPLICATED_USER are kept only when Gu1 resolves a match on a different entity. Otherwise they may be suppressed (metadata.kycCrossEntityDuplicates.suppressedWarnings). GUENO_CROSS_ENTITY_DUPLICATED is never omit-eligible.

Registry Cross-Check (Argentina / RENAPER)

When RENAPER double-check is enabled and a registry-related issue is surfaced as a warning code, the same strings may appear in warnings. Product locales map them under rejectionReasonCodes (in addition to warningRisks fallbacks where configured).

Code	Description
`RENAPER_DNI_MISSING`	Cross-check could not run: document number (DNI) was not available from verification.
`RENAPER_GENDER_MISSING`	Cross-check could not run: gender (M/F) is required for the registry.
`RENAPER_VERIFICATION_UNAVAILABLE`	The registry could not be reached or completed; retry later.
`RENAPER_DNI_NOT_MATCH`	Document number does not match the official registry.
`RENAPER_TRAMITE_DATA_MISSING`	Transaction number could not be compared: required data missing.
`RENAPER_TRAMITE_ID_NOT_MATCH`	Transaction number does not match the registry (e.g. outdated ID copy).
`RENAPER_NAME_NOT_MATCH`	OCR name is below the 80% similarity threshold vs RENAPER registry.
`RENAPER_EJEMPLAR_NOT_MATCH`	ID copy letter (ejemplar) does not match RENAPER registry.
`RENAPER_DOB_NOT_MATCH`	OCR date of birth does not match RENAPER `fecha_nacimiento`.
`RENAPER_EXPIRY_NOT_MATCH`	OCR expiration date does not match RENAPER `vencimiento`.
`RENAPER_BIOMETRIC_NOT_MATCH`	Selfie does not match the ID photo in the biometric registry.
`RENAPER_BIOMETRIC_UNAVAILABLE`	Biometric check could not be completed (network, credentials, or service).
`RENAPER_CREDENTIALS_REQUIRED`	RENAPER credentials are not configured for the organization.
`RENAPER_NOT_VALID_CREDENTIALS`	RENAPER credentials failed validation.

Example Response (ID Verification)

{
  "status": "approved",
  "verificationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "requestId": "req_abc",
  "extractedData": { "fullName": "Jane Doe", "documentNumber": "12345678" },
  "warnings": ["POSSIBLE_DUPLICATED_USER"]
}

Example Response (Face Match)

{
  "match": true,
  "score": 85,
  "status": "approved",
  "verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "warnings": []
}

ID Verification

Verify document front/back and extract data

Face Match

Compare document portrait and selfie

Getting Started

SDK

Use Cases

Webhooks

Workflows

Monitoring (entities)

Person

Messaging

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Payment Methods

Rules

Custom lists

Risk Matrix

Alerts

Investigations

Data Ingestion

Bulk imports

Documents

Enrichment

Services

Integrations

Interactive Tutorials

KYC Warning Risk Codes

Overview

Session-Based KYC Validation

ID Verification

Face Match

Liveness (Session-Based KYC)

AML (Session-Based KYC)

Device & IP Analysis (Session-Based KYC)

Internal (Gu1)

Registry Cross-Check (Argentina / RENAPER)

Example Response (ID Verification)

Example Response (Face Match)

ID Verification

Face Match

​Overview

​Session-Based KYC Validation

​ID Verification

​Face Match

​Liveness (Session-Based KYC)

​AML (Session-Based KYC)

​Device & IP Analysis (Session-Based KYC)

​Internal (Gu1)

​Registry Cross-Check (Argentina / RENAPER)

​Example Response (ID Verification)

​Example Response (Face Match)

ID Verification

Face Match

Overview

Session-Based KYC Validation

ID Verification

Face Match

Liveness (Session-Based KYC)

AML (Session-Based KYC)

Device & IP Analysis (Session-Based KYC)

Internal (Gu1)

Registry Cross-Check (Argentina / RENAPER)

Example Response (ID Verification)

Example Response (Face Match)