Skip to main content

API Reference

ID Bolt Session

The main class of ID Bolt is IdBoltSession. 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

create

SignatureDescription
static create(serviceUrl: string, options: IdBoltCreateSessionOptions): IdBoltSessionPrimary way to create an ID Bolt session.
Parameters
  • serviceUrl: string: URL that ID Bolt loads when started. Provided in your account on the Scandit dashboard.
note

The default value 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. Contact your Scandit account manager for more information.

  • options: IdBoltCreateSessionOptions: Object specifying the session options:
    • licenseKey: string: Your license key, provided in you account on the Scandit dashboard.
    • documentSelection: Document Selection: Object specifying the acceptable documents. See Document Selection.
    • returnDataMode: ReturnDataMode: Defines the extent of the data returned by the onCompletion() callback. Use:
      • ReturnDataMode.FullWithImages to get all extracted data and images.
      • ReturnDataMode.Full to get all extracted data without images.
    • anonymizationMode?: AnonymizationMode: Define the extend returned data is anonymized. See Anonymization Mode.
    • scanner?: Scanner: Options to customize the scanner. See Scanner.
    • validation?: Validators[]: Optional array of validators, default: []. See Validators.
    • locale?: string: The language in which the text is displayed. Default: "en-US".
    • workflow?: WorkflowOptions: Options to customize the workflow. See Workflow Options.
    • theme?: Theme: Options to customize the theme. See Theme.
    • textOverrides?: TextOverrides: Options to customize the text. See Text Overrides.
    • onCompletion: (result: CompletionResult) => void: A callback that is called when the user has successfully scanned their ID.
    • onCancellation?: (reason: CancellationReason) => void: A callback that is called whenever the flow can not be completed.

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("Successfully completed workflow");
},
onCancellation: (reason) => {
switch (reason) {
case CancellationReason.UserClosed:
console.log("User closed the scanning window");
break;
case CancellationReason.ServiceStartFailure:
console.log("ID Bolt service failed to start");
break;
}
}
});
await idBoltSession.start();

start

SignatureDescription
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.

Document Selection

Documents are selected using the DocumentSelection class.

A class to define which types of documents the ID Bolt will accept. The list of documents is provided as specific document objects, instantiated with a Region. For example passports from the USA would be new Passport(Region.USA).

Documents that are not acceptable may still get recognized by the scanner. In this case the user will be notified to use one of the accepted document types.

create

SignatureDescription
static DocumentSelection.create(selection: Selection): DocumentSelectionPrimary way to create a DocumentSelection instance with all the included and excluded documents. Only Selection.include is mandatory.
const documentSelection = DocumentSelection.create({
accepted: [
new Passport(Region.Any),
// You can either use country name or ISO code
new IDCard(Region.FRA),
new DriverLicense(Region.France)
],
rejected: [
// You can explicitly reject certain documents, if they would be included otherwise.
new Passport(Region.Switzerland)
],
});

Document Types

Document types are represented by classes. The general purpose document classes can all be instantiated with a specific region.

These document type instances are used to define which documents are accepted or rejected in the DocumentSelection class.

Passport

Includes all Passports

new Passport(Region.USA) // US passports
new Passport(Region.Any) // Any passport

ID Card

Includes national identity cards

new IDCard(Region.Germany) // German identity cards
new IDCard(Region.Any) // National identity card from any country

Driver License

Includes driver licenses

new DriverLicense(Region.France) // French driver license
new DriverLicense(Region.Any) // Driver license card from any country

Visa (ICAO)

Includes visas that comply with the International Civil Aviation Organization (ICAO) standards

new VisaIcao(Region.USA) // US ICAO-compliant visas
new VisaIcao(Region.Any) // Any ICAO-compliant visa

Residence Permit

Includes residence permits

new ResidencePermit(Region.USA) // US residence permits
new ResidencePermit(Region.Any) // Residence permit from any country

Health Insurance Card

Includes health insurance cards

new HealthInsuranceCard(Region.Germany) // German health insurance cards
new HealthInsuranceCard(Region.Any) // Health insurance card from any country

Region Specific Documents

In addition to the general purpose document classes, there are also region specific document. These documents are instantiated with the RegionSpecific class and a RegionSpecificSubtype argument.

Example:

new RegionSpecific(RegionSpecificSubtype.BelgiumMinorsId) // Belgian minors ID
new RegionSpecific(RegionSpecificSubtype.MexicoTaxId) // Mexican tax ID

The list of supported region specific document types can be found here.

Regions

Regions are used to define the region of a document. They can be used to define which documents are accepted or rejected in the DocumentSelection class.

Regions can be chosen using the Region enum. The Region enum contains both the ISO code and the name of the region. If your system uses three-letter ISO codes, you can also directly use those strings.

Example:

// France
Region.FRA;
Region.France;

Region.FRA === Region.France === "FRA"; // true

// Any
Region.Any;

Two-letter ISO code

If you have a two-letter ISO code, you can convert it to a region using the Region.fromShortCode method. To convert a region to a two-letter ISO code, use the Region.toShortCode method.

Example:

const region = Region.fromShortCode("FR"); // == Region.France == "FRA"
const shortCode = Region.toShortCode(Region.FRA); // == "FR"

In case the provided short code is not valid, the methods throw an exception.

Validators

Validators enable you to run checks on the scanned ID. They are only run on documents that are from the list of accepted documents.

The avaliablde validators can be created by using the Validators class.

The following validators are available:

Not Expired

The notExpired validator checks that the scanned document has not expired. This validator will not pass if the expiration date could not be determined from the extracted data.

	...
validation: [Validators.notExpired()],
...

Not Expired In

The notExpiredIn validator checks that the scanned document has still not expired after the duration passed in argument. This test will not pass if the expiration date could not be determined from the extracted data.

This validator takes a Duration object as argument with the following properties:

type Duration = {
days?: number;
months?: number;
}

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

	...
validation: [Validators.notExpiredIn({months: 12})],
...

US Real ID

The US.isRealID validator checks that the scanned driver license is compliant with the rules of Real ID defined by the American Association of Motor Vehicle Administrators (AAMVA). This validator will not pass if the scanned document is not an AAMVA document.

	...
validation: [Validators.US.isRealID()],
...

Callbacks

Methods

onCompletion

A callback that is called when the user has successfully scanned their ID and passed all validations.

ParameterTypeDescription
resultCompletionResultContains the scanning results including the captured ID data

The CompletionResult object contains:

  • capturedId: The scanned document data. See CapturedId. Will be null if no data was returned based on the returnDataMode.

Example:

	...
onCompletion: (result) => {
if (result.capturedId) {
console.log('Document type:', result.capturedId.documentType);
console.log('Full name:', result.capturedId.fullName);
console.log('Document number:', result.capturedId.documentNumber);
}
}
...

onCancellation

A callback that is called when the user closes the ID Bolt pop-up without completing the scanning process.

ParameterTypeDescription
reasonCancellationReasonThe reason why the scanning was cancelled

The CancellationReason enum contains:

  • CancellationReason.UserClosed: The user closed the ID Bolt pop-up before completing the scanning process
  • CancellationReason.ServiceStartFailure: The ID Bolt service failed to start

Example:

...
onCancellation: (reason) => {
switch (reason) {
case CancellationReason.UserClosed:
console.log("User closed the scanning window");
break;
case CancellationReason.ServiceStartFailure:
console.log("ID Bolt service failed to start");
break;
}
}
...

Result Data Types

CapturedId

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

Properties
PropertyTypeDefaultDescription
firstNamestringnull
lastNamestringnull
fullNamestring
sexstringnull
nationalitystringnull
addressstringnull
issuingCountryRegionnullThe ISO (Alpha-3 code) abbreviation of the issuing country of the document.
documentNumberstringnullA 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.
documentAdditionalNumberstringnull
personalIdNumberstringnullA unique identification number assigned to an individual, often for life, used for identification and administrative purposes (e.g., taxation, social security, or government records).
dateOfBirthDateResultnull
agenumbernull
dateOfExpiryDateResultnull
isExpiredbooleannull
dateOfIssueDateResultnull
documentTypeDocumentTypeOne of "Passport" | "IDCard" | "DriverLicense"
capturedResultTypesstring[]
imagesImageDatanullObject containing base64 encoded jpg images

ImageData

Properties
PropertyTypeDefaultDescription
fullFramestring[]nullRaw captured frame used for detection. Array of base64 encoded jpg images
croppedstring[]nullCropped face and ID images, if available. Array of base64 encoded jpg images

DateResult

An object representing a date.

Properties
PropertyType
daynumber
monthnumber
yearnumber

Return Data Mode

Values used by IdBoltCreateSessionOptions to define what data is returned by IdBoltSession.onCompletion(). Possible values are:

ValueDescription
FullAll extracted data is returned, but images are excluded.
FullWithImagesAll extracted data is returned, including images of the scanned ID.

Example:

	...
returnDataMode: ReturnDataMode.Full,
...

Anonymization Mode

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:

ValueDescription
NoneNo anonymization is applied (default)
FieldsOnlyOnly fields (data) are anonymized
ImagesOnlyOnly images are anonymized
FieldsAndImagesBoth fields and images are anonymized

Note that when image anonymization is enabled, the FullWithImages return data mode does not return full-frame images. Cropped images are still returned, if available.

Example:

	...
anonymizationMode: AnonymizationMode.FieldsOnly,
...

Workflow Options

Options to customize the user interface of the ID Bolt workflow.

Properties

PropertyTypeDescription
showWelcomeScreenbooleanWhen 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.
showResultScreenbooleanDetermines whether to show the result screen at the end of the workflow.

Example:

	...
workflow: {
showWelcomeScreen: false,
showResultScreen: true,
},
...

Scanner Options

The scanner used can be customized using the scanner option in IdBoltCreateSessionOptions.

By default, the scanner is set to SingleSideScanner with all modalities enabled.

The following scanners are available:

Single Side Scanner

The single side scanner extracts all data from a single side scan of the document. The scanning modalities can be chosen individually in the constructor.

	...
scanner: new SingleSideScanner(
true, // Enable reading of barcode ID-documents
true, // Enable reading of machine readable zone (MRZ) documents
true, // Enable reading of visual inspection zone (VIZ) documents
),
...

Full Document Scanner

The full document scanner forces the user to scan both the front and back side of the document. It uses all modalities enabled by default.

	...
scanner: new FullDocumentScanner(),
...

Theme

Options to customize the visual appearance of the ID Bolt interface.

Properties

colors

Object containing color definitions for various UI elements:

PropertyTypeDescription
primarystringThe primary color used throughout the interface
imagestringColor used for image-related elements
backgroundstringMain popup background color
backgroundSecondarystringSecondary background color, used for surfaces
backgroundInversestringInverse background color
textPrimarystringPrimary text color
textSecondarystringSecondary text color
textTertiarystringTertiary text color
textInversestringInverse text color
successstringColor for success states
errorstringColor for error states
warningstringColor for warning states
infostringColor for informational states
buttonBackgroundstringBackground color for buttons, defaults to primary
buttonTextstringText color for buttons, defaults to textInverse
buttonBorderstringBorder color for buttons, defaults to primary
buttonBackgroundDisabledstringBackground color for disabled buttons
buttonBorderDisabledstringBorder color for disabled buttons
buttonTextDisabledstringText color for disabled buttons

dimensions

Object containing dimension values for UI elements:

PropertyTypeDescription
radiusPopupstringBorder radius for the popup
radiusButtonstringBorder radius for buttons
radiusCardstringBorder radius for cards

Example:

	...
theme: {
colors: {
primary: "#007AFF"
},
dimensions: {
radiusButton: "8px"
}
}
...

Text Overrides

Text overrides are used to customize the text displayed in the ID Bolt interface. The text overrides are defined using the textOverrides option in IdBoltCreateSessionOptions.

The following texts can be overridden:

  • titles.SCANNER_HEADER: The header of the scanner screen.
  • titles.LOCAL_SCAN_HEADER: The header of the local scan screen.
  • texts.HELP_SUPPORTED_DOCUMENTS_INCLUDE_LIST: The list of documents that are accepted, as displayed in the help screen.
  • texts.HELP_SUPPORTED_DOCUMENTS_INCLUDE_LIST_BRIEF: A brief description of the documents that are accepted, as displayed in the main screen.
  • texts.HELP_SUPPORTED_DOCUMENTS_EXCLUDE_LIST: The list of documents that are excluded, as displayed in the help screen. Only shown if there are excluded documents.

Example:

    ...
textOverrides: {
"titles.SCANNER_HEADER": "Scan your Passport for John Doe",
"titles.LOCAL_SCAN_HEADER": "Scan your Passport for John Doe",
"texts.HELP_SUPPORTED_DOCUMENTS_INCLUDE_LIST": "Scan your passport, ID card or driver license",
"texts.HELP_SUPPORTED_DOCUMENTS_INCLUDE_LIST_BRIEF": "Scan your passport, ID card or driver license",
"texts.HELP_SUPPORTED_DOCUMENTS_EXCLUDE_LIST": "Not accepted are documents issued before 2000",
....

Supported Region Specific Documents

Region specific document types are instantiated with the RegionSpecific class and a RegionSpecificSubtype argument like new RegionSpecific(RegionSpecificSubtype.BelgiumMinorsId).

The following region specific document types are supported:

  • UsBorderCrossingCard
  • ChinaExitEntryPermit
  • UsGlobalEntryCard
  • ChinaMainlandTravelPermitTaiwan
  • UsNexusCard
  • ChinaMainlandTravelPermitHongKongMacau
  • ApecBusinessTravelCard
  • PakistanAfghanCitizenCard
  • SingaporeFinCard
  • UsGreenCard
  • MalaysiaIkad
  • MalaysiaMykad
  • MalaysiaMypr
  • MexicoConsularVoterId
  • GermanyEid
  • UsCommonAccessCard
  • PhilippinesMultipurposeId
  • MalaysiaMykas
  • MalaysiaMykid
  • MalaysiaMytentera
  • MexicoProfessionalId
  • MalaysiaRefugeeId
  • CanadaTribalId
  • UsUniformedServicesId
  • UsVeteranId
  • PhilippinesWorkPermit
  • SingaporeWorkPermit
  • UsWorkPermit
  • PhilippinesSocialSecurityCard
  • SwedenSocialSecurityCard
  • CanadaSocialSecurityCard
  • UsSocialSecurityCard
  • BelgiumMinorsId
  • ColombiaMinorsId
  • PeruMinorsId
  • BoliviaMinorsId
  • HungaryAddressCard
  • UkAsylumRequest
  • CanadaCitizenshipCertificate
  • SingaporeEmploymentPass
  • CanadaMinorsPublicServicesCard
  • MalaysiaMypolis
  • PhilippinesNbiClearance
  • IndiaPanCard
  • PhilippinesPostalId
  • PakistanProofOfRegistration
  • SingaporeSPass
  • SwedenSisId
  • ColombiaTemporaryProtectionPermit
  • UsTwicCard
  • UsWeaponPermit
  • CanadaWeaponPermit
  • IrelandPublicServicesCard
  • CanadaPublicServicesCard
  • PakistanConsularId
  • GuatemalaConsularId
  • MexicoConsularId
  • PhilippinesTaxId
  • MexicoTaxId
  • ChinaOneWayPermit
  • UsMedicalMarijuanaCard
  • UsMunicipalId
  • AustraliaAsicCard
  • UaeVehicleRegistrationCard

Supported Locales

The following languages are supported:

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