Skip to main content

​
Overview

The ID Verification, Face Match, and Liveness (session-based) APIs return a warnings field when the verification provider signals non-blocking issues or risk flags. warnings is an array of risk code strings (e.g. "POSSIBLE_DUPLICATED_USER", "LOW_FACE_MATCH_SIMILARITY"). Clients can use these codes for:
  • Display: Map each code to a human-readable message (e.g. via your own i18n or the descriptions below).
  • Logic: Branch on specific codes (e.g. show a different UX for DOCUMENT_EXPIRED vs POSSIBLE_DUPLICATED_USER).
The codes are per service: ID Verification, Face Match, and Liveness each have their own set. Below are the possible values for each.
If the provider 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.

​
ID Verification

Returned in POST /api/kyc/id-verification and GET /api/kyc/id-verification/verifications/:id in the warnings array.
CodeDescription
ID_DOCUMENT_IN_BLOCKLISTThe document has been identified as matching an entry in your document blocklist (e.g. previously marked as fraudulent, stolen, or otherwise problematic).
BARCODE_NOT_DETECTEDThe system could not find or read the barcode on the document; may be due to poor image quality or unsupported document type.
BARCODE_VALIDATION_FAILEDThe barcode could not be validated against other data on the document.
QR_NOT_DETECTEDThe system could not find or read the QR code on the document.
QR_VALIDATION_FAILEDThe QR code could not be validated against other data on the document.
MRZ_NOT_DETECTEDThe Machine Readable Zone (MRZ) could not be found or read.
MINIMUM_AGE_NOT_METThe user’s age is below the minimum required for the application.
DATA_INCONSISTENTOCR data and NFC chip data do not match; possible document tampering or data inconsistency.
COULD_NOT_RECOGNIZE_DOCUMENTThe system could not confirm the authenticity or validity of the document.
PORTRAIT_IMAGE_NOT_DETECTEDThe portrait image on the document could not be identified or processed.
DOCUMENT_NUMBER_NOT_DETECTEDThe document number could not be located or read.
DATE_OF_BIRTH_NOT_DETECTEDThe date of birth on the document could not be identified or processed.
EXPIRATION_DATE_NOT_DETECTEDThe expiration date on the document could not be identified or processed.
NAME_NOT_DETECTEDThe first name and/or last name on the document could not be identified or processed.
MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAMEDifferences between MRZ and OCR-extracted data; possible document alteration.
MRZ_VALIDATION_FAILEDThe MRZ does not meet the expected format or contains invalid data.
INVALID_DATEOne or more dates on the document are not valid or do not match expected formats.
DOCUMENT_EXPIREDThe document’s expiration date has passed.
DOCUMENT_NOT_SUPPORTED_FOR_APPLICATIONThe type of document provided is not accepted for the current verification process.
DOCUMENT_SIDES_MISMATCHThe sides of the document do not match the expected format or contain invalid data.
COULD_NOT_DETECT_DOCUMENT_TYPEThe system could not determine the type of document submitted.
DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTSThe name on this document does not match the name on other documents previously verified for this user.
POSSIBLE_DUPLICATED_USERThe system identified a potential duplicate user with previously approved documents from another session.
LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITYThe face captured during document scanning does not sufficiently match the portrait on the document.
FULL_NAME_MISMATCH_WITH_PROVIDEDThe provided full name does not match the data extracted from the document.
DOB_MISMATCH_WITH_PROVIDEDThe provided date of birth does not match the date extracted from the document.
GENDER_MISMATCH_WITH_PROVIDEDThe provided gender does not match the gender extracted from the document.
COUNTRY_MISMATCH_WITH_PROVIDEDThe provided country does not match the country extracted from the document.
NATIONALITY_MISMATCH_WITH_PROVIDEDThe provided nationality does not match the nationality extracted from the document.
IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDEDThe provided identification number does not match the document number, personal number, or tax number extracted from the document.
SCREEN_CAPTURE_DETECTEDThe submitted document appears to be a screen capture or photo of a document on a screen rather than a physical document.
PRINTED_COPY_DETECTEDThe submitted document appears to be a printed copy rather than an original official document.
PORTRAIT_MANIPULATION_DETECTEDPotential manipulation of the portrait area of the document was detected.
UNPARSED_ADDRESSThe address on the document could not be parsed or geolocated.
DOCUMENT_NUMBER_FORMAT_MISMATCHThe document number does not match the expected format for this type of document.
PERSONAL_NUMBER_FORMAT_MISMATCHThe personal number does not match the expected format for this type of document.
ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTSData extracted from multiple ID verification documents in this session do not match (e.g. name or date of birth).

​
Face Match

Returned in POST /api/kyc/face-match and GET /api/kyc/face-match/verifications/:id in the warnings array.
CodeDescription
LOW_FACE_MATCH_SIMILARITYThe facial features of the provided image do not closely match the reference image; potential identity mismatch.
NO_REFERENCE_IMAGEA 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.
CodeDescription
FACE_IN_BLOCKLISTThe face matches an entry in your face blocklist (e.g. previously blocklisted individual).
POSSIBLE_FACE_IN_BLOCKLISTThe system identified a possible face in the blocklist; the face is not allowed to be verified.
LOW_LIVENESS_SCOREThe liveness check resulted in a low score; possible non-live facial representation or poor-quality biometric data.
NO_FACE_DETECTEDThe system could not identify a face during the liveness check.
LIVENESS_FACE_ATTACKThe system detected a potential attempt to bypass the liveness check.
DUPLICATED_FACEThe system identified a duplicated face from another approved session.
POSSIBLE_DUPLICATED_FACEThis face may match another user already approved in the system.
MULTIPLE_FACES_DETECTEDMultiple faces were detected; the system uses the largest face for verification. (Passive Liveness only)
LOW_FACE_QUALITYThe facial image quality is below the acceptable threshold. (Passive Liveness only)
LOW_FACE_LUMINANCEThe facial image is too dark. (Passive Liveness only)
HIGH_FACE_LUMINANCEThe facial image is too bright or overexposed. (Passive Liveness only)

​
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