> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# KYC Warning Risk Codes
> Risk code strings for warnings in session-based KYC, ID Verification, Face Match, and Liveness — in the gu1 KYC API for identity verification flows.
## 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](/en/use-cases/kyc/create-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`](/en/use-cases/kyc/create-validation) 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)
```json theme={null}
{
"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)
```json theme={null}
{
"match": true,
"score": 85,
"status": "approved",
"verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"warnings": []
}
```
Verify document front/back and extract data
Compare document portrait and selfie