Skip to content

Document Recognition v2

The overview describes the common field interpretation rules, failure reasons, and full/light file formats.

Parent: document_recognition_v2_result. A separate format with text, images, and structured checks.

Fields of document_recognition_v2_result.

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Field JSON type Purpose and conditions
status string, enum Required: NOT_PARSED — not yet recognized; PENDING — processing; SUCCESS — successful; FAILED — error; NOT_FOUND — not found; COPIED — result reused.
source_session string, UUID Source session when the result is copied; otherwise absent.
optical_checks object Summary document checks, if generated; see the table below.
quality_checks object[] Quality checks by page. The array is returned even when it has no items ([]).
authenticity_checks object[] Authenticity checks. The array is returned even when it has no items ([]).
document_types object[] Recognized document types / variants. May be [].
visual_text_json object Dynamic dictionary of values from the document's visual zone; when data is available.
mrz_text_json object Dynamic dictionary of values from the machine-readable zone; when data is available.
images object[] Stored original and extracted images; may be [].
result boolean Stored technology result: true means accepted, false means a negative result. May be absent before calculation; consider the status and the details below.
failure_reason object Failure reason, if recorded; see the structure.

In visual_text_json and mrz_text_json, an entry containing a confidence key is returned as its value only; other values are preserved as stored. Therefore, do not expect a {value, confidence} wrapper for every field. Dictionary keys, value types, and completeness depend on the recognizer and document; nested null values are possible. This API does not return a separate combined confident_text_json field.

Parent: document_recognition_v2_result.optical_checks.

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Field JSON type Purpose and conditions
overall_status boolean Overall optical checks result.
doc_type boolean Document type check.
expiry boolean Validity period check.
image_qa boolean Summary image quality check.
mrz boolean Machine-readable zone check.
pages_count integer Number of pages in the checks array.
security boolean Security features check.
text boolean Text data check.

Parent: document_recognition_v2_result.quality_checks[].

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Field JSON type Purpose and conditions
image_glares boolean Glare check passed.
image_focus boolean Focus check passed.
image_resolution boolean Image resolution check passed.
image_colorness boolean Color check passed.
perspective boolean Perspective distortion check passed.
bounds boolean Document boundaries check passed.
portrait boolean Portrait check passed.
brightness boolean Brightness check passed.
page integer Page index in the checks array, starting at 0.

Parent: document_recognition_v2_result.authenticity_checks[].

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Field JSON type Purpose and conditions
liveness_electronic_device boolean Check for a document presented on an electronic device screen passed.
liveness_black_and_white_copy boolean Black-and-white copy check passed.
image_patterns boolean Graphic patterns check passed.
barcode_format boolean Barcode format check passed.
portrait_comparison boolean Portrait comparison check passed.
photo_embedding boolean Photo insertion / embedding check passed.
page integer Check page identifier from the processor; no universal range is defined.

For boolean checks, true means a positive check result and false means a negative one; an absent field means no value is available, not that the check passed.

Parent: document_recognition_v2_result.document_types[].

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Field JSON type Purpose and conditions
document_id integer Document identifier in the recognizer's classifier. The public field name is document_id.
name string Name of the recognized document / specimen.
type string Document type name.
type_id integer Numeric type code from the recognizer; no local enum is defined.
issue_year string Specimen issue year or period; specifically a string, not an integer.
issuing_country string Issuing country name.
has_rfid boolean Whether the document type has an RFID chip.
has_mrz boolean Whether the document type has a machine-readable zone.
format integer Format code from the recognizer; no local mapping of the numeric values is defined.
country_code string Country code, up to 3 characters.
prediction number Confidence score for type identification; scale and range are not defined.
required_light_schemes integer Required lighting schemes code from the recognizer; no mapping of the numeric values is defined.
authenticity_light_schemes integer Lighting schemes code for authenticity checks; no mapping of the numeric values is defined.
page integer Page number / index from the recognizer, a non-negative number.

Parent: document_recognition_v2_result.images[].

Conditions are specified in each row. Item order does not replace the page value.

Field JSON type Purpose and conditions
type string, enum Required. Image type, listed below.
content string When a file is available: Base64 in the full response, a URL in light.
page integer When a page number is available. Original files and image arrays use numbering from 0; a single document_front gets 0, while other single images may have no page number.

Values of document_recognition_v2_result.images[].type.

Allowed types; the presence of each type depends on the document and recognition results.

Field JSON type Purpose and conditions
unknown string unknown type
source string original image
portrait string portrait
fingerprint string fingerprint
eye string eye image
signature string signature
bar_code string barcode
proof_of_citizenship string proof of citizenship
document_front string front side
document_back string back side
document_rear string rear image from the recognizer; the distinction from back is not defined locally
color_dynamic string color-changing element
ghost_portrait string additional security portrait
stamp string seal / stamp
contact_chip string contact chip
finger_left_thumb string left thumb print
finger_left_index string left index finger print
finger_left_middle string left middle finger print
finger_left_ring string left ring finger print
finger_left_little string left little finger print
finger_right_thumb string right thumb print
finger_right_index string right index finger print
finger_right_middle string right middle finger print
finger_right_ring string right ring finger print
finger_right_little string right little finger print
finger_right_four string four fingers of the right hand
finger_left_four string four fingers of the left hand
finger_two_thumbs string both thumbs

JSON examples

Fragments of the root response object, not complete responses. All values and URLs are illustrative. File formats follow the explanations on this page.

{
  "document_recognition_v2_result": {
    "status": "COPIED",
    "result": true,
    "source_session": "44444444-4444-4444-8444-444444444444",
    "optical_checks": {
      "doc_type": true,
      "expiry": true
    },
    "quality_checks": [
      {
        "image_focus": true,
        "page": 0
      }
    ],
    "authenticity_checks": [],
    "document_types": [
      {
        "name": "Example document",
        "document_id": 100,
        "page": 0
      }
    ],
    "visual_text_json": {
      "surname": "SAMPLE",
      "given_names": "EXAMPLE",
      "fathers_name": null
    },
    "images": [
      {
        "type": "document_front",
        "page": 0,
        "content": "https://files.example.invalid/document/front.png"
      }
    ]
  }
}