Configuration Options

The SDK accepts a configuration object during initialization with the following options:

Core Settings

Option	Type	Default	Description
`lensFlavor`	string	Required	Determines scanning experience type: - `'document'`: Receipts & Invoices scanning - `'long_document'`: Long Receipts scanning - `'credit_card'`: Credit card scanning - `'checks'`: Check scanning (front/back) - `'upload'`: File upload only - `'anydocs'`: AnyDocs - `'caps'`: Bottle cap code capture - `'code_strips'`: Printed code strip capture - `'prescription_label'`: Prescription label video capture
`container`	string	`undefined`	HTML element ID where lens will mount. Creates full-screen overlay if not specified
`enableFullScreen`	boolean	`false`	Enable fullscreen mode for the camera view
`debug_mode`	boolean	`false`	Enables debug logging to console
`useDevApi`	boolean	`false`	Route SDK API requests to `lens-dev.veryfi.com` instead of production (`lens.veryfi.com`). Affects partner validation, send-cropped, send-package, `/api/document`, and `/api/blueprints`
`boxColor`	string	`"rgba(84, 192, 139, 0.6)"`	Color for the document detection bounding box (CSS color value)

Document Processing

Option	Type	Default	Description
`detectBlur`	boolean	`true`	Enable blur detection on captured images
`testBlurDetection`	boolean	`true`	Enable blur level calculation during crop (may slow capture)
`enforceDocumentDetection`	boolean	`false`	Forces document detection validation — prevents submission when no document detected (removes the "Submit Anyway" option from the modal)
`enforceBlurDetection`	boolean	`false`	Forces blur detection validation — prevents submission when image is blurry (removes the "Submit Anyway" option from the modal)
`autoDocumentCapture`	boolean	`false`	Enables automatic document capture when quality criteria are met (no manual capture button needed). Works with `document` and `anydocs` flavors

UI Elements

Option	Type	Default	Description
`enableSubmit`	boolean	`true`	Shows submit button after successful capture
`torchButton`	boolean	`true`	Show torch/flashlight toggle button (requires device support)
`torchOnStart`	boolean	`true`	Turn torch on when the camera starts
`switchCameraButton`	boolean	`true`	Show switch camera (front/back) button
`mirrorButton`	boolean	`true`	Show mirror/flip video button
`mirrorOnDesktop`	boolean	`true`	Automatically mirror the video on desktop (front-facing webcam)
`exitButton`	boolean	`false`	Adds button to close camera view
`isBlurModal`	boolean	`true`	Shows warning modal when blur is detected
`isDocumentModal`	boolean	`true`	Shows warning modal when no document is detected
`capCircleRadius`	number	`0.7`	Default circle radius for bottle cap overlay (requires `lensFlavor: 'caps'`)
`rectWidth`	number	`0.7`	Default width for code strip overlay (requires `lensFlavor: 'code_strips'`)
`rectHeight`	number	`0.08`	Default height for code strip overlay (requires `lensFlavor: 'code_strips'`)

Detection Thresholds

Option	Type	Default	Description
`blurThreshold`	number	`0.7`	Blur detection threshold (0–1). Higher values make blur detection stricter
`lcdThreshold`	number	`0.5`	LCD detection threshold (0–1). Higher values make LCD detection stricter

LCD Detection (Fraud Prevention)

Option	Type	Default	Description
`lcdDetectionForDocuments`	boolean	`false`	Enables LCD screen detection for receipts, invoices, and other document types
`lcdDetectionForChecks`	boolean	`false`	Enables LCD screen detection for check scanning
`lcdDetectionForCards`	boolean	`false`	Enables LCD screen detection for credit card scanning
`isLcdModal`	boolean	`true`	Shows warning modal when an LCD screen is detected
`enforceLcdDetection`	boolean	`false`	Forces LCD detection validation — prevents submission when LCD is detected (removes the "Submit Anyway" option from the modal)

Front/Back Detection (Check Side Classification)

Option	Type	Default	Description
`frontBackDetectionForChecks`	boolean	`false`	Enables front/back side classification for checks. Detects if the user captured the wrong side and shows a warning modal to retake (requires `lensFlavor: 'checks'`)

Local Field Extraction

On-device field detection runs on the crop preview before submit for receipt flavors. Uses Tesseract OCR plus a WASM classifier. Results are shown as labeled overlays on the preview and attached to the submit response as field_detection.

Option	Type	Default	Description
`documentFieldsToDetect`	`string[]`	`[]`	Fields to detect on the crop preview: `'vendor'`, `'date'`, `'total'`. Only applies to `document` and `long_document` flavors. Leave empty to disable
`disableSubmitUntilFieldDetectionDone`	boolean	`false`	Keep the submit button disabled until crop-preview field detection finishes. Only applies when `documentFieldsToDetect` is set

info

When documentFieldsToDetect is set, see the field_detection_* statuses above and field_detection on the onSuccess response. Configure options in Configuration.

Special Features

Option	Type	Default	Description
`enableLongReceiptPreview`	boolean	`false`	Shows preview during receipt stitching (requires `lensFlavor: 'long_document'`)
`packageMode`	boolean	`false`	When `true`, captured scans are bundled into a single zip uploaded to S3 at submit time; `/api/document` receives `package_path` instead of inline base64. See Decoupled Submission
`customData`	object	`{}`	Custom key-value data object included in document submissions. Must be a plain object (not an array or null)

Use VeryfiLens.setCustomSubmitHandler(handler) to override the default submission flow (not an init option). See Decoupled Submission.

Fingerprint Settings

Option	Type	Default	Description
`enforceFingerprint`	boolean	`false`	Requires device fingerprint generation to succeed. Throws an error if fingerprint generation fails
`disableFingerprint`	boolean	`false`	Disables device fingerprint generation entirely. Sets UUID to `'not_generated'` and removes stored fingerprint from localStorage

Check Processing

Option	Type	Default	Description
`captureBackOfCheck`	boolean	`false`	Enables back side capture for checks (requires `lensFlavor: 'checks'`)
`enforceBothSides`	boolean	`false`	Requires both sides of the check to be captured (requires `lensFlavor: 'checks'`)
`enforceAndSkipBothSides`	boolean	`false`	Requires both sides but automatically proceeds to back capture without prompting (requires `lensFlavor: 'checks'`)
`delayBetweenCaptures`	number	`0`	Delay in milliseconds between front and back capture (requires `lensFlavor: 'checks'`)
`checksEnableManualMode`	boolean	`true`	Enable/disable manual capture mode for checks when aspect ratio falls outside acceptable limits (requires `lensFlavor: 'checks'`)
`checksManualModeTimeout`	number	`3000`	Timeout in milliseconds before switching to manual mode (requires `lensFlavor: 'checks'`)
`checksMaxAspectRatio`	number	`2.61`	Maximum acceptable aspect ratio for check detection (requires `lensFlavor: 'checks'`)
`checksMinAspectRatio`	number	`2.61`	Minimum acceptable aspect ratio for check detection (requires `lensFlavor: 'checks'`)
`persistManualModeOnRetake`	boolean	`true`	Persist manual mode when retaking front side or capturing back side (requires `lensFlavor: 'checks'`)
`forceLandscapeCheckPreview`	boolean	`true`	Force horizontal/landscape orientation for check previews (requires `lensFlavor: 'checks'`)

Crop Settings

Option	Type	Default	Description
`cropMargin`	number	`0.0`	Margin around greenbox during cropping for all document types as percentage (0.0-1.0)
`checksCropMargin`	number	`0.1`	Margin around greenbox during cropping for checks as percentage (0.0-1.0, requires `lensFlavor: 'checks'`)
`cropLayoutAspectRatio`	number	`0.0`	Custom aspect ratio for the manual mode crop layout guide overlay (`0.0` = use default)

Crop Layout Overlay

Option	Type	Default	Description
`cropLayoutBorderColor`	string	`"#54C08B"`	Border color of the manual mode guide rectangle
`cropLayoutStroke`	number	`2`	Border width in pixels of the manual mode guide rectangle
`cropLayoutOverlayAlpha`	number	`0.6`	Transparency of the manual mode guide overlay (0-1)
`cropLayoutCornerRadius`	number	`0`	Corner radius in pixels of the manual mode guide rectangle

Checks Manual Mode Crop Layout Position & Size

Option	Type	Default	Description
`cropLayoutGuideTopPosition`	string	`"40%"`	Vertical position of the crop guide (CSS value, e.g., "40%", "200px")
`cropLayoutGuideLeftPosition`	string	`"50%"`	Horizontal position of the crop guide (CSS value, e.g., "50%", "100px")
`cropLayoutGuideWidthScale`	number	`0.90`	Width scale of guide relative to video width (0-1, where 0.90 = 90%)
`cropLayoutGuideMaxHeightScale`	number	`0.70`	Maximum height scale of guide relative to video height (0-1, where 0.70 = 70%)

Checks Manual Mode Crop Layout Tip Text Styling

Option	Type	Default	Description
`cropLayoutTipPosition`	string	`"right"`	Position of tip text relative to guide. Options: `"top"`, `"bottom"`, `"left"`, `"right"`
`cropLayoutTipFontFamily`	string	`"Arial, sans-serif"`	Font family for tip text
`cropLayoutTipFontSize`	string	`"16px"`	Font size for tip text (CSS value, e.g., "16px", "1rem")
`cropLayoutTipFontWeight`	string	`"bold"`	Font weight for tip text
`cropLayoutTipColor`	string	`"white"`	Color for tip text
`cropLayoutTipTextShadow`	string	`"0 1px 2px rgba(0,0,0,0.8)"`	Text shadow for tip text (CSS text-shadow value)
`cropLayoutTipOffset`	string	`"35%"`	Offset distance of tip text from guide edge (CSS value)

AnyDocs

Option	Type	Default	Description
`enableBlueprintsModal`	boolean	`false`	Show blueprints selection modal on init. Fetches available blueprints from `/api/blueprints`. Ignored when `selectedBlueprint` is set (requires `lensFlavor: 'anydocs'`)
`selectedBlueprint`	string	`null`	Pre-selected blueprint name. When set, skips the blueprints modal (requires `lensFlavor: 'anydocs'`)
`anydocMaxPages`	number	`null`	Maximum number of pages allowed. `null` means unlimited (requires `lensFlavor: 'anydocs'`)
`anydocAddPageText`	string	`'Add Page'`	Custom text for the add page button (requires `lensFlavor: 'anydocs'`)
`anydocSubmitText`	string	`'Submit'`	Custom text for the submit button (requires `lensFlavor: 'anydocs'`)
`anydocShowFlipMessage`	boolean	`false`	Shows a flip message after capturing a page (requires `lensFlavor: 'anydocs'`)
`anydocFlipMessageText`	string	`'Please flip the document and capture the other side'`	Custom message for the flip prompt (requires `lensFlavor: 'anydocs'` and `anydocShowFlipMessage: true`)
`anydocFlipContinueText`	string	`'Continue'`	Custom text for the continue button in the flip prompt (requires `lensFlavor: 'anydocs'` and `anydocShowFlipMessage: true`)

Prescription Label

Option	Type	Default	Description
`prescriptionLabelShowOverlay`	boolean	`true`	Shows the bottle-shaped cutout overlay that guides the user where to position the pill bottle (requires `lensFlavor: 'prescription_label'`)
`prescriptionLabelWidthRatio`	number	`0.55`	Width of the bottle overlay (0–1 relative to viewport, requires `lensFlavor: 'prescription_label'`)
`prescriptionLabelHeightRatio`	number	`0.65`	Height of the bottle overlay (0–1 relative to viewport, requires `lensFlavor: 'prescription_label'`)
`prescriptionLabelText`	string	`'Position prescription label in outline'`	Instructional text shown to the user (requires `lensFlavor: 'prescription_label'`)
`prescriptionLabelShowSquareOverlay`	boolean	`false`	Shows a square/rectangular overlay guide instead of (or in addition to) the bottle outline (requires `lensFlavor: 'prescription_label'`)
`prescriptionLabelSquareWidthRatio`	number	`0.8`	Square overlay width (0–1 relative to viewport, requires `lensFlavor: 'prescription_label'` and `prescriptionLabelShowSquareOverlay: true`)
`prescriptionLabelSquareHeightRatio`	number	`0.5`	Square overlay height (0–1 relative to viewport, requires `lensFlavor: 'prescription_label'` and `prescriptionLabelShowSquareOverlay: true`)
`prescriptionLabelShowGuide`	boolean	`false`	Show a semi-transparent guide explaining how to record the label. Auto-hides when recording starts and reappears on retake (requires `lensFlavor: 'prescription_label'`)
`prescriptionLabelGuideText`	string	(see below)	Guide text when the bottle outline overlay is active. Use `\n` for line breaks
`prescriptionLabelSquareGuideText`	string	(see below)	Guide text when the square overlay is active. Use `\n` for line breaks

info

For prescription labels, selectedBlueprint defaults to 'prescription_medication_label' when no blueprint is provided.

Default prescriptionLabelGuideText: "Position the bottle within the outline.\n\nPress the capture button to start recording, slowly rotate the bottle to capture the entire label and press the capture button again to stop recording."

Default prescriptionLabelSquareGuideText: "Position the prescription label within the square.\n\nPress the capture button to start recording, press again to stop."

Text Customization

Option	Type	Default	Description
`documentModalMessage`	string	`'Oops, There appears to be no document on your image'`	Custom message for document detection modal
`blurModalMessage`	string	`'Oops, The image is too blurry to process'`	Custom message for blur detection modal
`submitButtonText`	string	`'Submit Anyway'`	Custom text for submit button
`retakeButtonText`	string	`'Retake a picture'`	Custom text for retake button
`cropButtonText`	string	`'Crop'`	Custom text for crop button
`resetButtonText`	string	`'Reset'`	Custom text for reset button
`dropZoneText`	string	`'Click or drag and drop to upload an image'`	Custom text for upload drop zone (requires `lensFlavor: 'upload'`)
`lcdModalMessage`	string	`'LCD screen detected. Please capture a printed document instead'`	Custom message for LCD detection modal
`wrongSideFrontMessage`	string	`'This looks like the back of the check. Please flip and capture the front side.'`	Custom message shown when back side is detected during front capture (requires `frontBackDetectionForChecks: true`)
`wrongSideBackMessage`	string	`'This looks like the front of the check. Please flip and capture the back side.'`	Custom message shown when front side is detected during back capture (requires `frontBackDetectionForChecks: true`)
`checkEnforcedModalMessage`	string	`'Please flip the check and capture the back side'`	Custom message when back check capture is required (requires `lensFlavor: 'checks'` and `enforceBothSides: true`)
`checkOptionalModalMessage`	string	`'Do you want to capture the back side of the check?'`	Custom message when back check capture is optional (requires `lensFlavor: 'checks'` and `captureBackOfCheck: true`)
`checkContinueButtonText`	string	`'Continue'`	Custom text for check continue button (requires `lensFlavor: 'checks'` and `enforceBothSides: true`)
`checkYesButtonText`	string	`'Yes'`	Custom text for check confirmation button (requires `lensFlavor: 'checks'`)
`checkNoButtonText`	string	`'No'`	Custom text for check rejection button (requires `lensFlavor: 'checks'`)
`bottleCapText`	string	`'Position bottle cap in circle'`	Default instruction text for bottle cap overlay
`codeStripsText`	string	`'Position code strip in rectangle'`	Default instruction text for code strip overlay
`cropLayoutTipMessage`	string	`'Position check inside rectangle'`	Instructional text shown with the crop layout overlay in manual mode

Option	Type	Default	Description
`onCloseRedirectUrl`	string	`undefined`	URL to redirect to when exit pressed
`onClose`	function	`undefined`	Callback when camera view closes: `(isVisible: boolean) => void`

Usage Examples

Document Scanning

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "document",
    torchButton: true,
    exitButton: true,
    isBlurModal: true,
    isDocumentModal: true,
    debug_mode: true,
    documentModalMessage: "Please ensure a document is visible in the frame",
    blurModalMessage: "Image is too blurry, please try again",
    submitButtonText: "Process Document",
    retakeButtonText: "Capture Again"
});

Check Scanning with Manual Mode

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "checks",
    captureBackOfCheck: true,
    enforceBothSides: true,
    checksEnableManualMode: true,
    checksManualModeTimeout: 3000,
    checksMaxAspectRatio: 2.7,
    checksMinAspectRatio: 1.8,
    checksCropMargin: 0.1,
    persistManualModeOnRetake: true,
    forceLandscapeCheckPreview: false,
    // Checks manual mode crop layout overlay styling
    cropLayoutBorderColor: "#54C08B",
    cropLayoutStroke: 2,
    cropLayoutOverlayAlpha: 0.6,
    cropLayoutCornerRadius: 0,
    // Checks manual mode crop layout positioning
    cropLayoutGuideTopPosition: "40%",
    cropLayoutGuideLeftPosition: "50%",
    cropLayoutGuideWidthScale: 0.90,
    cropLayoutGuideMaxHeightScale: 0.70,
    // Checks manual mode crop layout tip text
    cropLayoutTipMessage: "Align check within the guide",
    cropLayoutTipPosition: "bottom",
    cropLayoutTipFontSize: "18px",
    cropLayoutTipColor: "white",
    torchButton: true,
    exitButton: true
});

Document Scanning with LCD Detection

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "document",
    torchButton: true,
    exitButton: true,
    lcdDetectionForDocuments: true,
    isLcdModal: true,
    enforceLcdDetection: false,
    lcdThreshold: 0.4,
    lcdModalMessage: "LCD screen detected. Please capture a printed document instead"
});

Check Scanning with LCD Detection

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "checks",
    captureBackOfCheck: true,
    enforceBothSides: true,
    torchButton: true,
    exitButton: true,
    lcdDetectionForChecks: true,
    isLcdModal: true,
    enforceLcdDetection: true,
    lcdThreshold: 0.4
});

Check Scanning with Front/Back Detection

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "checks",
    captureBackOfCheck: true,
    enforceBothSides: true,
    torchButton: true,
    exitButton: true,
    frontBackDetectionForChecks: true,
    wrongSideFrontMessage: "This looks like the back of the check. Please flip and capture the front side.",
    wrongSideBackMessage: "This looks like the front of the check. Please flip and capture the back side."
});

AnyDocs

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "anydocs",
    torchButton: true,
    exitButton: true,
    isBlurModal: true,
    isDocumentModal: true,
    anydocMaxPages: 10,
    anydocAddPageText: "Add Page",
    anydocSubmitText: "Submit All",
    anydocShowFlipMessage: true,
    anydocFlipMessageText: "Please flip the document and capture the other side",
    anydocFlipContinueText: "Continue"
});

Prescription Label

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "prescription_label",
    torchButton: true,
    exitButton: true,
    prescriptionLabelShowOverlay: true,
    prescriptionLabelWidthRatio: 0.55,
    prescriptionLabelHeightRatio: 0.65,
    prescriptionLabelText: "Position prescription label in outline",
    selectedBlueprint: "prescription_medication_label",
    preferredVideoFormat: "video/mp4"
});

Automatic Document Capture

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "document",
    autoDocumentCapture: true,
    torchButton: true,
    exitButton: true,
    isBlurModal: true,
    isDocumentModal: true
});

Local Field Extraction

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "document",
    documentFieldsToDetect: ["vendor", "date", "total"],
    disableSubmitUntilFieldDetectionDone: true,
    torchButton: true,
    exitButton: true
});

Custom Submit Handler

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "document",
    torchButton: true,
    exitButton: true
});

VeryfiLens.setCustomSubmitHandler((image, packageInfo) => {
    console.log("Custom handler received image:", image);
    console.log("Package info (when packageMode: true):", packageInfo);
    // Process image with your own API instead of Veryfi's
});

Custom Data with Submission

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "document",
    torchButton: true,
    exitButton: true,
    customData: {
        userId: "user-123",
        department: "accounting",
        projectCode: "PRJ-456"
    }
});

Dynamic Configuration

You can update configuration during runtime:

info

All settings except lensFlavor and container can be updated during runtime.

VeryfiLens.configureLens({
    isBlurModal: false,
    torchButton: false
});

Configuration Options

Core Settings​

Document Processing​

UI Elements​

Detection Thresholds​

LCD Detection (Fraud Prevention)​

Front/Back Detection (Check Side Classification)​

Local Field Extraction​

Special Features​

Fingerprint Settings​

Check Processing​

Crop Settings​

Crop Layout Overlay​

Checks Manual Mode Crop Layout Position & Size​

Checks Manual Mode Crop Layout Tip Text Styling​

AnyDocs​

Prescription Label​

Text Customization​

Navigation & Callbacks​

Usage Examples​

Document Scanning​

Check Scanning with Manual Mode​

Document Scanning with LCD Detection​

Check Scanning with LCD Detection​

Check Scanning with Front/Back Detection​

AnyDocs​

Prescription Label​

Automatic Document Capture​

Local Field Extraction​

Custom Submit Handler​

Custom Data with Submission​

Dynamic Configuration​

Core Settings

Document Processing

UI Elements

Detection Thresholds

LCD Detection (Fraud Prevention)

Front/Back Detection (Check Side Classification)

Local Field Extraction

Special Features

Fingerprint Settings

Check Processing

Crop Settings

Crop Layout Overlay

Checks Manual Mode Crop Layout Position & Size

Checks Manual Mode Crop Layout Tip Text Styling

AnyDocs

Prescription Label

Text Customization

Navigation & Callbacks

Usage Examples

Document Scanning

Check Scanning with Manual Mode

Document Scanning with LCD Detection

Check Scanning with LCD Detection

Check Scanning with Front/Back Detection

AnyDocs

Prescription Label

Automatic Document Capture

Local Field Extraction

Custom Submit Handler

Custom Data with Submission

Dynamic Configuration