--- Source: https://docs.microblink.com/blinkid/scanning-settings Title: Scanning settings Description: Reference for BlinkID scanning settings --- # Scanning settings {/* TODO add variants for self-hosted; or link to them */} 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). :::note[Session settings] On mobile and web platforms, you can also additionally configure [session settings](session-settings.md). ::: ## `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](session-settings.md#inputimagesource). 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](session-settings.md#scanningmode). 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](session-settings.md#scanningmode). 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. {/* TODO explain document rules in another article and link to it from here */} 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](session-settings.md#scanningmode). 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](session-settings.md#inputimagesource). 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` {/* TODO this is unclear and probably needs an example */} 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. {/* TODO here we're talking about ProcessingStatus, but we never introduce this subject; should probably be linked in the same way we link to session settings in other entries */} 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. {/* TODO same as with blur rejections */} 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. {/* TODO same comment for other rejections; we have introduced none of these nor linked to them */} 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. {/* TODO same comment for other rejections; we have introduced none of these nor linked to them */} 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](session-settings.md#inputimagesource). 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. {/* TODO document rules are undefined */} 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](scan-barcodes.md). --- ### `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](session-settings.md#scanningmode). 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](glossary.md#mrz). 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](session-settings.md#scanningmode). 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](glossary.md#viz). 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](session-settings.md#scanningmode). 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. ::: {/* TODO this doesn't actually make sense, we just said that it must be on the front, but now we allow it on the back. What? */} 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. {/* TODO again with the document rules */} 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. {/* TODO again with the ProcessingStatus */} 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](session-settings.md#inputimagesource). 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. ## Related articles - [BlinkID session settings](session-settings.md) - [BlinkID settings validation](settings-validation.md) - [Extract document images](image-return.md) - [Custom and default redaction](redaction.md) Last updated on Jul 24, 2026