Scandit ID Bolt

ID Bolt is a pre-built ID scanning workflow that seamlessly integrates into any website allowing users to scan their identity documentation in just one second.. ID Bolt works on-device, via desktop and mobile in a unified solution, ensuring no identity information is collected by third-party servers and reduces latency for quick scanning performance.

Learn more about ID Bolt at https://www.scandit.com/products/id-bolt/.

Get started

Add the ID Bolt client as a dependency:

npm i @scandit/web-id-bolt

Copy the following snippet to get started.

Your application defines when the ID Bolt pop-up is opened. In this snippet, we open it after a click on a button present in the page:

import {
	Passport,
	IdCard,
	DriverLicense,
	VisaIcao,
	DocumentSelection,
	IdBoltSession,
	Region,
	ReturnDataMode,
	Validators,
} from "@scandit/web-id-bolt";

const ID_BOLT_URL = "https://app.id-scanning.com";

const LICENSE_KEY = "-- YOUR LICENSE KEY HERE --";

async function startIdBolt() {
	// define which documents are allowed to be scanned. More complex rules can be added.
	const documentSelection = DocumentSelection.create({
		accepted: [
			new Passport(Region.Any),
			new IdCard(Region.Any),
			new DriverLicense(Region.Any),
			new VisaIcao(Region.Any),
		],
	});
	// initialization of the ID Bolt session
	const idBoltSession = IdBoltSession.create(ID_BOLT_URL, {
		licenseKey: LICENSE_KEY,
		documentSelection,
		// define what data you expect in the onCompletion listener (set below)
		returnDataMode: ReturnDataMode.Full,
		// add validation rules on the scanned document
		validation: [Validators.notExpired()],
		locale: "en",
		onCompletion: (result) => {
			// the ID has been captured and validation was successful. In this example the result
			// will contain the document data because `returnDataMode` was set to ReturnDataMode.Full.
			alert(`Thank you ${result.capturedId?.fullName ?? ""}`);
		},
		onCancellation: (reason) => {
			// the ID Bolt pop-up has been terminated without a succesful scan
		},
	});
	// open the pop-up
	await idBoltSession.start();
}

// open ID Bolt when some button is clicked
const someButton = document.getElementById("someButton");
someButton.addEventListener("click", startIdBolt);

For completeness this is the HTML you will need for the example:

<button id="someButton">Start ID Bolt</button>

If you have Content-Security-Policy headers (CSP) which prevent loading iframes on your page, you need to adapt the value like so:

frame-src 'self' https://app.id-scanning.com https://id-service.scandit.com

API

IdBoltSession

The main class of ID Bolt. It represents a session in which the end-user is guided through a workflow to scan their ID. The IdBoltSession.onCompletion() callback is called when the user has scanned their ID, the ID has been accepted and the ID Bolt pop-up is closed. Similarly, IdBoltSession.onCancellation() is called when the user closes the ID Bolt pop-up without finishing the full process successfully.

Using validators, ID Bolt can verify the expiration date or other features of the ID. Optionally, this can be done without sharing any personally identifiable information (PII) with your website.

Methods

static create(serviceUrl: string, options: IdBoltCreateSessionOptions): IdBoltSession

Primary way to create an ID Bolt session.

• serviceUrl: string: the URL that ID Bolt loads when started. Provided in your account on the Scandit dashboard. Note: app.id-scanning.com is an alias that points to Scandit's servers. In a production environment it can be changed to your own domain name pointing to Scandit's servers. This will require you to configure a CNAME record in the DNS settings of your domain.
• options: IdBoltCreateSessionOptions: an object specifying the session options:
  • licenseKey: string: your license key, provided in you account on the Scandit dashboard.
  • documentSelection: DocumentSelection: an object specifying the acceptable documents. See DocumentSelection further below.
  • returnDataMode: ReturnDataMode: defines the extent of the data returned by the onCompletion() callback. Use ReturnDataMode.FullWithImages to get all extracted data and images, or ReturnDataMode.Full to get all extracted data without images.
  • validation?: Validators[]: an optional array of validators. See Validators further below. Default: []
  • locale?: string: the language in which the text is displayed. Default: "en-US".
  • textOverrides?: TextOverrides: override the translation of some texts in the UI
  • workflow?: WorkflowOptions: Options to customize the workflow. See WorkflowOptions further below.
  • theme?: Theme: Options to customize the theme. See Theme further below.
  • scanner?: Scanner: Options to customize the scanner behavior. See Scanner further below.
  • anonymizationMode?: AnonymizationMode: Controls how sensitive data is handled. See AnonymizationMode section below.
  • onCompletion: (result: CompletionResult) => void: A callback that is called when the user has successfully scanned their ID. Depending on the ReturnDataMode value you passed in IdBoltSession, result.capturedId will contain the document data or null.
  • onCancellation?: (reason: CancellationReason) => void: A callback that is called when the user has closed the ID Bolt pop-up without having finished the scanning workflow. The reason parameter indicates why the scan was cancelled.
  • keepAliveForNextSession?: boolean: When set to true, keeps the ID Bolt session alive after completion for potential reuse in subsequent sessions. This can improve performance for users who may need to scan multiple documents in sequence. Default: false.
  • disableCloseOnBrowserBack?: boolean: When set to true, prevents the ID Bolt pop-up from closing when the user presses the browser's back button. This can be useful in setups with custom navigation logic. Default: false.
  • externalTransactionId?: string: An optional tracking identifier supplied to this ID-Bolt session coming from your internal systems, such as a booking or order id. This can be used for better analytics.
  • featureFlags?: FeatureFlags: Optional feature flags to enable experimental or beta features.

Once created, a session object does nothing until you execute start() on it:

const idBoltSession = IdBoltSession.create(ID_BOLT_URL, {
	licenseKey: LICENSE_KEY,
	documentSelection,
	returnDataMode: ReturnDataMode.FullWithImages,
	validation: [Validators.notExpired()],
	onCompletion: (result) => alert(`Thanks ${result.capturedId?.fullName}`),
});
await idBoltSession.start();

async IdBoltSession.start(): Promise<string>

Open the ID Bolt pop-up to start the scanning workflow. This method returns a session ID identifying the session.

DocumentSelection

A class to define which types of documents the ID Bolt will accept. The list of documents is provided as couples of Region and DocumentType, for example passports from the USA.

Not accepted documents may still get recognized by the scanner. In this case the user will be notified to use one of the accepted document types.

Methods

static DocumentSelection.create(selection: Selection): DocumentSelection

Primary way to create a DocumentSelection instance with all the accepted and rejected documents.

Only Selection.accepted is mandatory.

The Selection interface has the following properties:

• accepted: Document[]: An array of accepted document types (required)
• rejected?: Document[]: An optional array of rejected document types

Example:

const documentSelection = DocumentSelection.create({
	accepted: [new Passport(Region.FRA)],
	rejected: [new DriverLicense(Region.CHE)],
});

Document Types

Each type of document is represented as its own class.

Passport

Represents passports of a specific region

Example:

new Passport(Region.USA);

IdCard

Represents id cards of a specific region

Example:

new IdCard(Region.USA);

DriversLicense

Represents drivers licenses of a specific region

Example:

new DriversLicense(Region.USA);

VisaIcao

Represents visas of a specific region that comply with the International Civil Aviation Organization (ICAO) standards

Example:

new VisaIcao(Region.USA);

ResidencePermit

Represents residence permits of a specific region

Example:

new ResidencePermit(Region.USA);

HealthInsuranceCard

Represents health insurance cards of a specific region

Example:

new HealthInsuranceCard(Region.DEU);

RegionSpecific

Represents region-specific document types that don't fall into the standard categories above. This class requires a specific subtype from the RegionSpecificSubtype enum.

Example:

import { RegionSpecific, RegionSpecificSubtype } from "@scandit/web-id-bolt";

// US Green Card
new RegionSpecific(RegionSpecificSubtype.UsGreenCard);

// US Social Security Card
new RegionSpecific(RegionSpecificSubtype.UsSocialSecurityCard);

// Malaysia MyKad
new RegionSpecific(RegionSpecificSubtype.MalaysiaMykad);

// Singapore Work Permit
new RegionSpecific(RegionSpecificSubtype.SingaporeWorkPermit);

For a complete list of available region-specific document subtypes, see the Scandit ID Bolt documentation.

Validators

Validators allow to run checks on the scanned ID. Validators are only run on accepted documents.

Validators.notExpired()

Checks that the document has not expired.

Note that this test will not pass if the expiration date could not be determined from the extracted data.

Validators.notExpiredIn(duration: Duration)

Checks that the document has still not expired after the duration passed in argument.

Duration is an object with following properties:

• days?: number
• months?: number

One of Duration.days and Duration.months has to be provided.

In the following example, the ID must not expire in the next 12 months:

const idBoltSession = IdBoltSession.create(ID_BOLT_URL, {
	licenseKey: LICENSE_KEY,
	documentSelection: ...,
	returnDataMode: ReturnDataMode.FullWithImages,
	validation: [Validators.notExpiredIn({months: 12})],
});

Note that this test will not pass if the expiration date could not be determined from the extracted data.

Validators.US.isRealID()

Checks that the scanned driver license is compliant with the rules of Real ID defined by the American Association of Motor Vehicle Administrators (AAMVA).

Note that this test will not pass if the scanned document is not an AAMVA document.

Locale

The locale is specified as a string. At least the following languages are supported, for a complete list see Scandit docs.

• en-US
• de-DE
• de-CH
• es-ES
• fr-FR
• it-IT
• nl-NL
• pl-PL
• pt-PT
• da-DK

TextOverrides

Some texts can be replaced with your own. If you use TypeScript, you will get autocompletion for the possible keys.

| key | Purpose and location | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | titles.LOCAL_SCAN_HEADER | The title above the scanner (local scan) | | titles.SCANNER_HEADER | The title above the scanner in the handover scenario (remote scan). | | texts.HELP_SUPPORTED_DOCUMENTS_INCLUDE_LIST_BRIEF | A brief text appearing on the welcome screen describing the main documents that are supported. | | texts.HELP_SUPPORTED_DOCUMENTS_INCLUDE_LIST | A text describing the full list of supported documents. Appears on the help screen. | | texts.HELP_SUPPORTED_DOCUMENTS_EXCLUDE_LIST | A text describing the full list of excluded documents. Appears on the help screen. |

Any translation key not in the allowed list will trigger a warning in the console and will be discarded.

Example usage:

const idBoltSession = IdBoltSession.create(ID_BOLT_URL, {
	licenseKey: LICENSE_KEY,
	locale: "en-US",
	textOverrides: {
		"titles.LOCAL_SCAN_HEADER": "Scan passport of John Sample",
		"titles.SCANNER_HEADER": "Scan passport of John Sample",
	},
});

WorkflowOptions

The WorkflowOptions object allows you to customize the user interface of the ID Bolt workflow. It has the following properties:

• showWelcomeScreen: boolean: Determines whether to display the welcome screen at the beginning of the workflow.
  • When enabled: Always shown on both desktop and mobile.
  • When disabled: Only shown on desktop to allow users to select between scanning on local device or handing over. On mobile, it skips directly to the scanner.
• showResultScreen: boolean: Determines whether to show the result screen at the end of the workflow.

Example usage:

const idBoltSession = IdBoltSession.create(ID_BOLT_URL, {
	licenseKey: LICENSE_KEY,
	documentSelection: ...,
	returnDataMode: ReturnDataMode.FullWithImages,
	workflow: {
		showWelcomeScreen: false,
		showResultScreen: true,
	}
});

Scanner

The Scanner option allows you to customize the scanning behavior. ID Bolt provides two scanner types:

SingleSideScanner

The SingleSideScanner class allows you to configure which document zones should be scanned.

Constructor

new SingleSideScanner(
	barcode: boolean,
	machineReadableZone: boolean,
	visualInspectionZone: boolean,
	additionalOptions?: SingleSideScannerAdditionalOptions
)

Parameters:

• barcode: boolean: Enable scanning of barcodes (e.g., on driver's licenses)
• machineReadableZone: boolean: Enable scanning of Machine Readable Zone (MRZ) found on passports and ID cards
• visualInspectionZone: boolean: Enable scanning of the Visual Inspection Zone (VIZ) - the human-readable text on documents
• additionalOptions?: SingleSideScannerAdditionalOptions: Optional additional configuration:
  • enforceVizForPassportScan?: boolean: When set to true, it forces the scanner to only accept a passport scan, when the Visual Inspection Zone (VIZ) was scanned successfully along with the Machine Readable Zone (MRZ). If set to false (default), a passport scan can get accepted when only the Machine Readable Zone (MRZ) has been read. This option can reduce global passport support coverage.

Example usage:

import { SingleSideScanner } from "@scandit/web-id-bolt";

const idBoltSession = IdBoltSession.create(ID_BOLT_URL, {
	licenseKey: LICENSE_KEY,
	documentSelection: ...,
	returnDataMode: ReturnDataMode.Full,
	scanner: new SingleSideScanner(
		true,  // barcode
		true,  // machineReadableZone
		true,  // visualInspectionZone
		{ enforceVizForPassportScan: true }
	),
	onCompletion: (result) => { ... }
});

FullDocumentScanner

The FullDocumentScanner class scans all available zones (barcode, MRZ, and VIZ) with no customization options.

import { FullDocumentScanner } from "@scandit/web-id-bolt";

const idBoltSession = IdBoltSession.create(ID_BOLT_URL, {
	licenseKey: LICENSE_KEY,
	documentSelection: ...,
	returnDataMode: ReturnDataMode.Full,
	scanner: new FullDocumentScanner(),
	onCompletion: (result) => { ... }
});

AnonymizationMode

Some countries have specific requirements for the anonymization of documents. ID-Bolt can be configured to not extract those sensitive fields from documents. Black boxes cover sensitive data in result images.

The AnonymizationMode enum has the following values:

| Value | Description | | ----------------- | ------------------------------------- | | None | No anonymization is applied | | FieldsOnly | Only fields (data) are anonymized | | ImagesOnly | Only images are anonymized | | FieldsAndImages | Both fields and images are anonymized |

Example usage:

const idBoltSession = IdBoltSession.create(ID_BOLT_URL, {
	licenseKey: LICENSE_KEY,
	documentSelection: ...,
	returnDataMode: ReturnDataMode.Full,
	anonymizationMode: AnonymizationMode.FieldsOnly,
});

Note that when anonymization for images is enabled, full frame images are not available in the result, as those images are captured before processing.

Theme

The Theme object allows you to customize the visual appearance of the ID Bolt interface. It has the following optional properties:

colors

An object containing color definitions for various UI elements:

• primary: The primary color used throughout the interface
• image: Color used for image-related elements
• background: Main popup background color
• backgroundSecondary: Secondary background color, used for surfaces
• backgroundInverse: Inverse background color
• backgroundScannerPlaceholder: Background color for scanner placeholder
• textScannerPlaceholder: Text color for scanner placeholder
• textPrimary: Primary text color
• textSecondary: Secondary text color
• textTertiary: Tertiary text color
• textInverse: Inverse text color
• success: Color for success states
• error: Color for error states
• warning: Color for warning states
• info: Color for informational states
• buttonBackground: Background color for buttons, defaults to primary
• buttonText: Text color for buttons, defaults to textInverse
• buttonBorder: Border color for buttons, defaults to primary
• buttonBackgroundDisabled: Background color for disabled buttons
• buttonBorderDisabled: Border color for disabled buttons
• buttonTextDisabled: Text color for disabled buttons
• connectionStatusConnectingBackground: Background color for connection status pills in connecting/waiting state
• connectionStatusConnectingText: Text color for connection status pills in connecting/waiting state
• connectionStatusSuccessBackground: Background color for connection status pills in success state
• connectionStatusSuccessText: Text color for connection status pills in success state
• connectionStatusErrorBackground: Background color for connection status pills in error/failed state
• connectionStatusErrorText: Text color for connection status pills in error/failed state
• headerButtons: Color for the header back and close buttons (when not in their white variant). Defaults to a medium gray.
• divider: Color for divider lines, such as the one on the QR code page. Defaults to a light gray.

dimensions

An object containing dimension values for UI elements:

• radiusPopup: Border radius for the popup
• radiusButton: Border radius for buttons
• radiusCard: Border radius for cards

images

An object allowing you to customize the images used in key screens:

• welcome: Custom image displayed on the welcome screen
• flowCompleted: Custom image displayed on the completion screen
• acceptedId: Custom image displayed as a placeholder for an accepted image, when picture is not captured

Image requirements:

• Format: PNG, JPEG, SVG, or WebP (must be provided as data URLs with appropriate mime types)
• Maximum size: 50KB per image
• Data URL format: Must start with one of the following prefixes:
  • data:image/png
  • data:image/jpeg
  • data:image/svg+xml
  • data:image/webp

fonts

An object allowing you to customize the fonts used in the interface:

• primary: An object containing different font weights for the primary font:
  • normal: Regular font weight (400)
  • semibold: Semi-bold font weight (600)
  • bold: Bold font weight (700)

Font requirements:

• Format: WOFF2, WOFF, TTF, or OTF (must be provided as data URLs)
• Maximum size: 100KB per font file
• Data URL format: Must start with appropriate mime type prefixes (e.g., data:font/woff2, data:font/woff)

styleOverrides

An object allowing you to apply custom CSS to specific UI elements:

• button: Custom CSS for buttons
• link: Custom CSS for links
• title: Custom CSS for titles

All properties are optional and should be specified as string values (e.g., color codes for colors, pixel or rem values for dimensions). Only the values specified will be used, all other values will be set to their default values.

Examples

Customizing colors

const theme = {
	colors: {
		primary: "#820900",
		image: "#820900",
	},
};

Customizing dimensions

const theme = {
	dimensions: {
		radiusButton: "22px", // Border radius for buttons
	},
};

Customizing images

const theme = {
	images: {
		welcome: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
		flowCompleted: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0i...",
		acceptedId: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...",
	},
};

Customizing fonts

const theme = {
	fonts: {
		primary: {
			normal: "data:font/woff2;base64,d09GMgABAAAAAAT...",
			semibold: "data:font/woff2;base64,d09GMgABAAAAAAU...",
			bold: "data:font/woff2;base64,d09GMgABAAAAAAV...",
		},
	},
};

Customizing styles with CSS

const theme = {
	styleOverrides: {
		// Custom CSS for buttons
		button: `
			.bolt-button {
  display: block;
  width: 100%;
  padding: 12px 24px;
  background-color: #fcb700;
  color: #000000;
  text-align: center;
  font-weight: bold;
  font-size: 16px;
  line-height: 1.5;
  text-decoration: none;
  border: none;
  cursor: pointer;
  box-sizing: border-box;
  border-radius: 0;
  box-shadow: none;
  transition: background-color 0.2s ease-in-out;
}

.bolt-button:hover,
.bolt-button:focus {
  background-color: #e0a800; /* Slightly darker yellow for hover */
  outline: none;
}
		`,

		// Custom CSS for links
		link: `
			.bolt-link {
				text-decoration: none;
				border-bottom: 1px dotted currentColor;
			}
			.bolt-link:hover {
				border-bottom: 1px solid currentColor;
			}
		`,

		// Custom CSS for titles
		title: `
			.bolt-title {
				text-transform: uppercase;
				letter-spacing: 0.05em;
			}
		`,
	},
};

Customizing the popup container with CSS

You can apply additional styling to the ID Bolt popup container directly from your application's CSS. This is particularly useful for customizing the popup's outer appearance like box shadow or border radius:

/* In your application's CSS */
idbolt-pop-up::part(container) {
	box-shadow: 0 0 20px 5px rgba(0, 0, 0, 0.2);
	border-radius: 16px;
}

Note that this approach only affects the popup container itself and not elements inside the popup. For customizing the internal elements, use the Theme API described above.

interface CompletionResult

The interface defining the result object received in the onCompletion callback.

CompletionResult:

• capturedId: CapturedId | null: Contains all the extracted data from the scanned document.

enum CancellationReason

Values used by the onCancellation callback to indicate why the scanning was cancelled.

CancellationReason:

• UserClosed: The user manually closed the ID Bolt pop-up.
• ServiceStartFailure: The scanning service failed to start.

interface CapturedId

The interface defining the object you receive in CompletionResult.capturedId.

CapturedId:

• firstName: string | null
• lastName: string | null
• fullName: string | null
• sex: string | null
• nationality: string | null
• address: string | null
• issuingCountry: RegionISO | null: The ISO (Alpha-3 code) abbreviation of the issuing country of the document.
• documentNumber: string | null: A unique identifier assigned to an individual document, such as an identification card or passport. This number is specific to the document itself and may change if a new document is issued.
• documentAdditionalNumber: string | null
• dateOfBirth: DateResult | null
• age: number | null
• dateOfExpiry: DateResult | null
• isExpired: boolean | null
• dateOfIssue: DateResult | null
• documentType: DocumentType | null
• documentSubtype: string | null
• capturedResultTypes: string[]
• images: { front: ImageSet; back: ImageSet; } | null: object containing base64 encoded data URL images for front and back of the document:
  • front: ImageSet: images captured from the front of the document
  • back: ImageSet: images captured from the back of the document
  • Each ImageSet contains:
    • face: string | null: cropped face image extracted from the document
    • croppedDocument: string | null: cropped image of the document, only available when the visual inspection zone is scanned
    • frame: string | null: full frame image of the captured document
• mrzResult: MrzResult | null: Raw data captured from MRZ (Machine Readable Zone)
• vizResult: VizResult | null: Raw data captured from VIZ (Visual Inspection Zone)

interface DateResult

An object representing a date.

DateResult:

• day: number | null
• month: number | null
• year: number

const Region

An enumeration of regions (mostly countries).

Example:

// France
Region.France;

// Any (world wide)
Region.Any;

enum DocumentType

An enumeration of the available main document types.

DocumentType:

• Passport
• IdCard
• DriverLicense
• VisaIcao
• ResidencePermit
• RegionSpecific
• HealthInsuranceCard

enum ReturnDataMode

Values used by IdBoltCreateSessionOptions to define what data is returned by IdBoltCreateSessionOptions.onCompletion().

ReturnDataMode:

• Full: all extracted data is returned, but images are excluded.
• FullWithImages: all extracted data is returned, including images of the scanned ID.