Result response

When the transaction is in state COMPLETED, the response from GET /document/validate/{transactionId} includes the full diagnostic:

Response example

{
  "transactionId": "1c7d...e9",
  "status": "COMPLETED",
  "diagnostic": "DECLINED",
  "rejectionReason": 160,
  "diagnostics": [
    {
      "code": "160",
      "result": "fail",
      "reason": "Presentation attack detected",
      "category": "attack_detection"
    },
    {
      "code": "500",
      "result": "pass",
      "reason": "Poor front image quality",
      "category": "integrity"
    },
    {
      "code": "501",
      "result": "pass",
      "reason": "Poor back image quality",
      "category": "integrity"
    },
    {
      "code": "502",
      "result": "pass",
      "reason": "Identity mismatch between portrait and ghost image",
      "category": "biometric"
    },
    {
      "code": "503",
      "result": "pass",
      "reason": "Mismatch estimated age selfie vs portrait",
      "category": "logical"
    },
    {
      "code": "504",
      "result": "pass",
      "reason": "Mismatch estimated sex selfie vs portrait",
      "category": "logical"
    }
  ],
  "ocr": {
    "mrz": {
      "documentType": "ID",
      "issuingState": "NIC",
      "documentNumber": "6191000E",
      "nationality": "NIC",
      "dateOfBirth": "2003-02-14",
      "expiryDate": "2029-11-20",
      "sex": "M",
      "surname": "ROMERO LOPEZ",
      "givenNames": "ELVIN ANTONIO",
      "mrzValid": true
    },
    "viz": {
      "documentClassification": ["NIC-00-IDC-2017-001-01-01"],
      "vizType": "VIZ_similar_to_ID_document"
    }
  },
  "timestamp": "2026-06-26T12:00:05.000Z"
}

Optional fields (diagnostic, rejectionReason, diagnostics, ocr, failureReason) are omitted from the response when they do not apply, instead of being sent with value null. For example, a diagnostic = APPROVED never includes rejectionReason. The rows of diagnostics[] are independent results for each check (result = pass or fail): there may be rows with result = fail even when the overall diagnostic is APPROVED, if that specific check was not determining for the final result. When status = FAILED, the response includes only transactionId, status, failureReason and timestamp.

Main fields

Field	Description
diagnostic	APPROVED | DECLINED | DOUBTFUL. It is included only when status = COMPLETED. DOUBTFUL only appears in automatic mode (see Service modes).
rejectionReason	Service catalog reason code, populated if diagnostic = DECLINED or diagnostic = DOUBTFUL.
diagnostics[]	Details of the individual validations performed (code, result, reason, category).
ocr.mrz	Data extracted from the machine-readable zone (MRZ) of the document.
ocr.viz	Document classification based on its visual zone (VIZ).

diagnostics

Field	Type	Description
code	string	Service catalog reason code.
result	string	pass | fail. Result of that specific validation.
reason	string	Human-readable description of the validation.
category	string	Thematic grouping: input, integrity, logical, biometric, attack_detection, unsupported, low_confidence, processing, block_list, escalated_review, unknown.

Reason code catalog (rejectionReason / diagnostics[].code)

It is useful to distinguish two levels of reading the result:

• Overall. The field diagnostic (APPROVED / DECLINED / DOUBTFUL) is the overall verdict of the transaction, and rejectionReason is the general code that summarizes the reason when diagnostic = DECLINED or diagnostic = DOUBTFUL.

• Granular. Each row of diagnostics[] is an individual signal (code + result = pass|fail), whose code comes from this same catalog. There may be signals fail even with a APPROVED, and signals that accompany any result (see codes 500-506).

These codes are stable. They should be treated as a closed catalog and this table should be consulted to present messages to the end user.

code	reason	category
100	Document front image missing	input
101	Document back image missing	input
102	Document front not detected	integrity
103	Document back not detected	integrity
104	Error loading front image	input
105	Error loading back image	input
106	Unsupported dimensions for front image	integrity
107	Unsupported dimensions for back image	integrity
108	Unsupported aspect ratio for front image	integrity
109	Unsupported aspect ratio for back image	integrity
110	Unsupported depth for front image	integrity
111	Unsupported depth for back image	integrity
112	Multiple documents detected on front image	attack_detection
113	Multiple documents detected on back image	attack_detection
120	Document annulled or damaged	integrity
130	Document MRZ invalid hashes	logical
131	Document expired	logical
132	Document MRZ not detected	logical
133	Document MRZ dates inconsistent	logical
134	Document MRZ invalid format	logical
150	Document photo missing	biometric
160	Presentation attack detected	attack_detection
161	Manipulation attack detected	attack_detection
170	Selfie face not detected	integrity
171	Identity mismatch between portrait and selfie image	biometric
200	Face matched in global block list	block_list
201	Face matched in platform block list	block_list
300	Fast-Auto-Screening document version not supported	unsupported
310	Fast-Auto-Screening country not supported	unsupported
311	Potential presentation attack detected	attack_detection
312	Potential manipulation attack detected	attack_detection
320	Fast-Auto-Screening low confidence score	low_confidence
330	Timeout whilst waiting for the OCR service	processing
331	Error calling OCR pipeline	processing
332	Mismatch between VIZ and the MRZ fields	logical
340	VIZ birthdate mismatch with MRZ	logical
341	VIZ country mismatch with MRZ	logical
342	VIZ document type mismatch with MRZ	logical
343	VIZ document number mismatch with MRZ	logical
344	VIZ expiry date mismatch with MRZ	logical
345	VIZ given names mismatch with MRZ	logical
346	VIZ nationality mismatch with MRZ	logical
347	VIZ second optional data mismatch with MRZ	logical
348	VIZ optional data mismatch with MRZ	logical
349	VIZ sex mismatch with MRZ	logical
350	VIZ surname mismatch with MRZ	logical
500	Poor front image quality	integrity
501	Poor back image quality	integrity
502	Identity mismatch between portrait and ghost image	biometric
503	Mismatch estimated age selfie vs portrait	logical
504	Mismatch estimated sex selfie vs portrait	logical
505	Mismatch estimated age portrait vs mrz	logical
506	Mismatch estimated sex portrait vs mrz	logical
600	Escalated validation declined	escalated_review
601	Escalated validation flagged for manual review	escalated_review
602	Escalated validation timed out	escalated_review
603	Escalated validation not completed	escalated_review
999	Validation declined	unknown

Codes 100-171 and 300-350 accompany a rejection or an inconclusive result: absent or illegible inputs (input), document integrity/quality problems (integrity), logical MRZ and VIZ↔MRZ comparison inconsistencies (logical), presentation or manipulation attacks (attack_detection), results of the fast auto-screening version/country and confidence (unsupported / low_confidence) and errors in the OCR pipeline itself (processing). Codes 200/201 indicate a match in the face blocklist, global or platform-specific. Codes 500-506 are informative verification signals (image quality and biometric age/sex matches between selfie, portrait, and MRZ): they appear as rows of diagnostics[] (result = pass or fail) and can accompany any state, including APPROVED; they are not used as rejectionReason on their own. Codes 600-603 correspond to a rejection, review, expiration, or abandonment during an escalated additional verification when the initial analysis is inconclusive.

The codes that accompany an inconclusive, including those in the 300-350 range, are the ones that the rejectionReason of a diagnostic = DOUBTFUL in the automatic mode. In hybrid mode that same case is resolved after the additional verification, and the final reason is the one corresponding to that resolution.

Rejection due to quality vs fraud detection

Not all DECLINED mean the same thing. The category for each code makes it possible to distinguish three situations and communicate the appropriate message to the end user:

• Capture or quality problem (categories input e integrity): the image is unusable or the document is not detected correctly. It is not an accusation of fraud. Includes missing/illegible inputs (100, 101, 104, 105) and integrity/quality problems (102, 103, 106-111, 120, 170, 500, 501). Typical action: request a new capture with better quality.

• Fraud or attack signal (categories attack_detection and block_list): genuine rejection due to signs of fraud. Includes multiple documents or presentation/manipulation attacks (112, 113, 160, 161), their variant potential, when the analysis detects signs without confirming them (311, 312), and matches in the face blocklist (200, 201).

• Data or biometric inconsistency (categories logical and biometric): the data are not consistent with each other, without being a pure quality problem or an explicit attack. Includes MRZ inconsistencies and VIZ↔MRZ comparison inconsistencies (130-134, 332, 340-350) and biometric comparisons (171, 502-506).

OCR data

Field (ocr.mrz)	Description
documentType	Document type (e.g. ID, PASSPORT).
issuingState	Issuing country (ISO code).
documentNumber	Document number.
nationality	Holder's nationality.
dateOfBirth	Date of birth.
expiryDate	Document expiry date.
sex	Sex registered on the document.
surname / givenNames	Surnames and given names.
mrzValid	true if the MRZ is valid (checksums correct).

Field (ocr.viz)	Description
documentClassification	Classification identifier(s) of the detected document model.
vizType	Type of visual zone recognized in the document.