Skip to main content
Version: v8001

Scanning settings

You can configure BlinkID scanning through its scanning settings.

BlinkID's extraction configuration is split into four modules. Each module targets a different part of the document. A valid scanning session must have at least one module enabled.

All four modules are enabled by default. To disable a module, set it to null (web, Android) or nil (iOS).

Session settings

On mobile and web platforms, you can also additionally configure session settings.

documentCaptureModule​

documentCaptureModule controls how document images are captured.

cropType​

type: string, default: not-cropped

Specifies whether the input image is already cropped, likely cropped, or not cropped.

Allowed values: not-cropped, unknown, cropped.

  • not-cropped: the image is treated as raw and goes through document detection and perspective correction
  • unknown: the image may already be cropped; the recognizer first attempts extraction as if the image is cropped, then falls back to the regular process if extraction fails
  • cropped: the input image must consist solely of the already cropped and perspective-corrected document
note

This setting is interdependent with the input image source.

The unknown and cropped values are applicable only to photo sources and will cause a validation error for video sources.

unsupportedDocumentsAllowed​

type: boolean, default: false

Enables the scanning and processing of unsupported document types.

A document is considered unsupported if its classification result is OTHER.

secondSideWithNoExtractableDataSkipped​

type: boolean, default: true

Indicates whether the back side scan should be skipped if that side supports image capture only (no MRZ, Barcode, etc.).

Some documents have a back side that is supported for capture but contains no extractable data. These sides can be captured only.

When true, processing stops after the front side for these documents. When false, the back side is captured even if no data is extracted.

note

This setting is interdependent with scanning mode.

If the scanning mode is set to automatic, secondSideWithNoExtractableDataSkipped can be toggled as needed to optimize the flow. However, if the scanning mode is set to single, then secondSideWithNoExtractableDataSkipped must remain true. Since only one side is captured in this mode, setting it to false will result in a settings validation failure.

passportDataPageScanOnly​

type: boolean, default: true

Indicates whether only the passport data page (the page containing the MRZ) should be scanned.

If set to false, the scanning process will require a second page scan for certain passport types that support it.

note

This setting is interdependent with scanning mode.

If the scanning mode is set to automatic, passportDataPageScanOnly can be toggled as needed to optimize the flow. However, if the scanning mode is set to single, then passportDataPageScanOnly must remain true. Since only one side is captured in this mode, setting it to false will result in a settings validation failure.

faceImageExtractionEnabled​

type: boolean, default: false

Enables the extraction of the document's face image.

If face image is present on the document, an extraction becomes mandatory for supported documents. The requirement for its presence is determined by document rules.

For unsupported documents, presence is optional.

faceImagePresenceMandatory​

type: boolean, default: false

If set to true, face image presence will be mandatory for the scanned document.

note

This setting is interdependent with scanning mode.

If the scanning mode is set to automatic, document side with the face image must be scanned first.

In case of a timeout and advancement to the next step in the scanning flow, if a face image is detected on the scanned side but cannot be extracted, the presence requirement is considered fulfilled. As a result, face image extraction will no longer be a requirement to complete the scan on next side.

inputImageReturnEnabled​

type: boolean, default: false

Indicates whether input images should be returned in the result.

Saves the input images at the moment of data extraction or timeout. This significantly increases memory consumption. Scanning performance is not affected.

documentImageReturnEnabled​

type: boolean, default: false

Indicates whether the perspective-corrected, tightly cropped document image should be returned in the result.

inputImageMargin​

type: float, default: 0.02

Defines the minimum required margin between the document and the edge of the input image, expressed as a percentage of the image dimensions.

This setting ensures compliance with regulations in certain countries that mandate documents be stored with adequate visual margins.

Allowed values: 0.0 to 1.0.

note

This setting is interdependent with the input image source.

This setting is not applicable to video sources and will cause a validation error if set to true.

note

The setting is ignored if cropType is set to cropped.

dotsPerInch​

type: integer, default: 250

The resolution of the returned document, face, and signature images in dots per inch.

Allowed values: 100 to 400.

extensionFactor​

type: float, default: 0.0

Expands the document crop boundary outward by a fraction of the document's longest edge.

Allowed values: 0.0 to 1.0.

blurSensitivityLevel​

type: string, default: mid

Controls how aggressively blur is detected in the document image.

Allowed values: off, low, mid, high.

  • low: less sensitive; what is detected is almost certainly blur, but mild blur may go undetected
  • mid: balanced default
  • high: highly sensitive; may flag slight out-of-focus as blur
  • off: blur detection disabled

imageWithBlurRejected​

type: boolean, default: true

Indicates whether frames with detected blur should be rejected.

When true, blurry frames are excluded from processing and ProcessingStatus is set to ImagePreprocessingFailed. When false, blurry frames are still processed and the blur status is reported in the result.

glareSensitivityLevel​

type: string, default: mid

Controls how aggressively glare is detected in the document image.

Allowed values: off, low, mid, high.

  • low: less sensitive; what is detected is almost certainly glare, but mild glare may go undetected
  • mid: balanced default
  • high: highly sensitive; may flag minor reflections as glare
  • off: glare detection disabled

imageWithGlareRejected​

type: boolean, default: true

Indicates whether frames with detected glare should be rejected.

When true, frames with glare are excluded from processing and ProcessingStatus is set to ImagePreprocessingFailed. When false, frames with glare are still processed and the glare status is reported in the result.

tiltSensitivityLevel​

type: string, default: mid

Controls how aggressively document tilt is detected in the image.

Allowed values: off, low, mid, high.

  • low: less sensitive; tolerates more tilt before rejecting a frame
  • mid: balanced default
  • high: highly sensitive; rejects frames with even slight tilt
  • off: tilt detection disabled

imageWithPoorLightingRejected​

type: boolean, default: true

Indicates whether frames with poor lighting conditions should be rejected.

Poor lighting is reported as TooBright or TooDark in ImageAnalysisLightingStatus.

When true, such frames are excluded from processing and ProcessingStatus is set to ImagePreprocessingFailed. When false, such frames are still processed and the lighting status is reported in the result.

imageWithHandOcclusionRejected​

type: boolean, default: true

Indicates whether frames where a hand occludes part of the document should be rejected.

When true, occluded frames are excluded from processing and ProcessingStatus is set to ImagePreprocessingFailed. When false, occluded frames are still processed and the occlusion status is reported in the result.

inputImageSelectionStrategy​

type: string, default: balanced

The strategy used to select the best input image from a pool of stable input images.

Before the best-quality image is selected, a sequence of stable input images must be collected. An input image is considered stable when the image analysis results are consistent across a consecutive stream of input images. A larger pool increases the likelihood of capturing a high-quality image but may introduce a slight delay.

Allowed values: single-image, optimize-for-speed, balanced, optimize-for-quality.

  • single-image: selects the first acceptable stable input image
  • optimize-for-speed: faster processing, but may select a lower-quality image because a smaller pool of stable input images is considered
  • balanced: trade-off between quality and speed
  • optimize-for-quality: slower processing in order to select a high-quality input image, because a larger pool of stable input images is considered
note

This setting is interdependent with the input image source.

This setting is only applicable to video sources.

barcodeModule​

barcodeModule reads various barcode formats such as PDF417, QR, and others.

If a barcode is present on the document, an extraction becomes mandatory if supported.

For supported documents, the requirement for its presence is determined by document rules. For unsupported documents, presence is optional.

This setting can function independently of document capture module; see how to use BlinkID as a barcode scanner.

presenceMandatory​

type: boolean, default: false

If set to true, barcode presence becomes mandatory for the scanned document.

note

This setting is interdependent with scanning mode.

If the scanning mode is set to single, then the barcode must be present on the scanned side. If the scanning mode is set to automatic, it must be present on one of the scanned sides.

In case of a timeout and advancement to the next step in the scanning flow, if a barcode is detected on the scanned side but cannot be extracted, the presence requirement is considered fulfilled. As a result, barcode extraction will no longer be a requirement to complete the scan on next side.

barcodeImageReturnEnabled​

type: boolean, default: false

Indicates whether a crop of the detected barcode should be returned in the result.

The dotsPerInch and extensionFactor settings do not affect the returned barcode image.

pdf417ScanningEnabled​

type: boolean, default: true

Enables scanning and processing of PDF417 barcodes.

qrScanningEnabled​

type: boolean, default: true

Enables scanning and processing of QR codes.

upceScanningEnabled​

type: boolean, default: false

Enables scanning and processing of UPC-E barcodes.

upcaScanningEnabled​

type: boolean, default: false

Enables scanning and processing of UPC-A barcodes.

code128ScanningEnabled​

type: boolean, default: false

Enables scanning and processing of Code 128 barcodes.

code39ScanningEnabled​

type: boolean, default: false

Enables scanning and processing of Code 39 barcodes.

ean8ScanningEnabled​

type: boolean, default: false

Enables scanning and processing of EAN-8 barcodes.

ean13ScanningEnabled​

type: boolean, default: false

Enables scanning and processing of EAN-13 barcodes.

itfScanningEnabled​

type: boolean, default: false

Enables scanning and processing of ITF barcodes.

dataMatrixScanningEnabled​

type: boolean, default: false

Enables scanning and processing of Data Matrix barcodes.

aztecScanningEnabled​

type: boolean, default: false

Enables scanning and processing of Aztec barcodes.

mrzModule​

mrzModule reads the machine-readable zone.

It has only one field:

presenceMandatory​

type: boolean, default: false

If set to true, MRZ presence becomes mandatory for the scanned document regardless of document rules.

note

This setting is interdependent with scanning mode.

If the scanning mode is set to single, then the MRZ must be present on the scanned side. If the scanning mode is set to automatic, it must be present on one of the scanned sides.

In case of a timeout and advancement to the next step in the scanning flow, if an MRZ is detected on the scanned side but cannot be extracted, the presence requirement is considered fulfilled.

vizModule​

vizModule reads the visual inspection zone. It contains the following fields:

presenceMandatory​

type: boolean, default: false

If set to true, VIZ presence becomes mandatory for the scanned document.

note

This setting is interdependent with scanning mode.

If the scanning mode is set to single, then the VIZ must be present on the scanned side. If the scanning mode is set to automatic, VIZ must be present on the front side of the document.

In case of a timeout, if VIZ was not fully extracted from the front side, extraction continues on the back side if VIZ is present there.

signatureImageExtractionEnabled​

type: boolean, default: false

Enables extraction of the cardholder's signature image, if supported.

For supported documents, signature image extraction is determined by document rules. For unsupported documents, extraction is not performed.

characterValidationEnabled​

type: boolean, default: true

Indicates whether OCR character validation is enabled.

When true, each field's OCR result is validated against the expected character set for that field. All fields must pass validation for a successful scan.

If an invalid character is detected, ProcessingStatus is set to InvalidCharactersFound.

resultAggregationEnabled​

type: boolean, default: true

Indicates whether OCR results should be aggregated across multiple video frames.

When true, results are combined from multiple frames to improve extraction accuracy. When false, the engine searches for a single optimal frame, which yields higher image quality but may be slower.

note

This setting is interdependent with the input image source.

This setting is not applicable to photo sources.

maxAllowedMismatchesPerField​

type: integer, default: 0

The maximum allowed mismatches per field during data matching.

Configures the maximum number of characters per field that can be inconsistent during data matching. By default, no mismatches are allowed.

When set to 0, the engine rejects any result where the same field extracted by two different modules (for example, MRZ date of birth and VIZ date of birth) does not match exactly. Increase this value only when scanning degraded or partially damaged documents where minor extraction errors are expected.

Last updated on