JS Plugin
The Javascript (JS) Plugin is the recommended way to add Vouched to your web application.

JS Plugin Flow
- Create your public key
- Copy the Quick Start Code below or follow the recipe to add Vouched to your site
Camera RestrictionsBrowser permissions for the camera require an
httpshost. Sites hosted withhttporfile://will not work. For testing purposes, alocalhostsite is a viable option.
Quick start code
VouchedLifetime considerationsThe
Vouchedfunction and subsequent calls to.mount()should only happen once per verification session otherwise multiple instances of the plugins which is not supported and may lead to severe issues.
<!DOCTYPE html>
<html>
<head>
<!-- utf-8 is required for JS Plugin default fonts -->
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<script src="https://static.vouched.id/plugin/releases/latest/index.js"></script>
<script type='text/javascript'>
(function() {
var vouched = Vouched({
// Optional verification properties.
verification: {
// verify the user's information
firstName: 'Gladys',
lastName: 'West',
// used for the crosscheck feature
email: '[email protected]',
phone: '000-111-2222'
},
liveness: 'enhanced',
publicKey: '<PUBLIC_KEY>',
// your webhook for POST verification processing
callbackURL: 'https://website.com/webhook',
// mobile handoff
crossDeviceQRCode: true,
crossDeviceSMS: true,
// called when the verification is completed.
onDone: (job) => {
// token used to query jobs
console.log("Scanning complete", { token: job.token });
// An alternative way to update your system based on the
// results of the job. Your backend could perform the following:
// 1. query jobs with the token
// 2. store relevant job information such as the id and
// success property into the user's profile
fetch(`/yourapi/idv?job_token=${job.token}`);
// Redirect to the next page based on the job success
if( job.result.success){
window.location.replace("https://website.com/success/");
}else{
window.location.replace("https://website.com/failed/");
}
},
// theme
theme: {
name: 'avant',
},
});
vouched.mount("#vouched-element");
})();
</script>
</head>
<body>
<div id='vouched-element' style="height: 100%"/>
</body>
</html>Basic react example
import React, { useEffect, useRef } from 'react';
/**
* This component will mount the `Vouched` verification plugin and unmount it when the component is no longer rendered.
*/
const VouchedComponent = () => {
const id = 'vouched-container';
const vouchedRef = useRef();
// You must ensure the `Vouched` function is only called once per verification session.
useEffect(() => {
// Assuming vouched is included via script tag or otherwise loaded
if (!window.Vouched || vouchedRef.current) {
return;
}
const instance = window.Vouched({
// your configuration
});
vouchedRef.current = instance;
instance
.mount(`#${id}`)
.then(() => {
// optionally await mounting, usually not required when using callbacks.
console.log('vouched mounted');
});
return () => {
instance.unmount(`#${id}`);
};
}, []);
return <div id={id} />;
};Versioning considerations
Note about legacy versioning schemeFor historic & compatibility reasons the plugin located at
https://static.vouched.id/widget/vouched-2.0.0.jsis available until we announce its deprecation.
Future npm packageWe are currently working on publishing a version of our plugin via npm, we expect to ship this with
v3of the plugin.This will allow you to leverage tools such as Dependabot to make automatic updates.
The vouched plugin is released according to semantic versioning.
We generally recommend embedding the latest version of plugin as we make frequent fixes and improvements to our plugin.
However while we try to keep breaking changes at a minimum certain changes may negatively impact when automatically adopting majorversion changes.
In order to restrict automatic embedding of future versions you can pin the version of the plugin you wish to use to major,minoror specific version.
Example
- Always using the latest version
https://static.vouched.id/plugin/releases/latest/index.js - Pinning
majorversion onlyhttps://static.vouched.id/plugin/releases/v2/index.js - Pinning
majorandminorhttps://static.vouched.id/plugin/releases/v2.0/index.js - Pinning to exact
patchversionhttps://static.vouched.id/plugin/releases/v2.0.0/index.js
A note on Sub Resource Integrity
SRI is only supported when using fully qualified versions since the contents of the files served under not fully qualified are mutable.
Examples
latestis not fully qualifiedv3andv3.2are not fully qualified since the minor and patch version may implicitly change.v3.2.1is fully qualified
In order to use SRI we suggest following this guide.
Layout Considerations
When integrating Vouched into your site design, consider that the Vouched component occupies 100% height of the parent container (it has CSS rule height: 100% applied). That means the parent container should be given a height.
Height should be given, for example, by setting height value (height: 100%) on the container or by using flex constraints (flex-grow: 1 in vertical flex-box).
On a desktop device, you will see different results depending on your crossDeviceQRCode, and crossDeviceSMS values. If they are all true as shown in the above code example, you can read more details on our Mobile Handoff page. If these fields are not present or set to false, you will see the following:
Javascript Callbacks
A callback is a function that is to be executed after another function has finished executing — hence the name "call back". Functions can take other functions as arguments. Functions that do this are called higher-order functions. Any function that is passed as an argument is called a callback function.
In the context of Vouched, the callback functions can be used to send data back to your server or interact with your app as desired. Some examples are onSubmit (this function is called when a user submits a photo), onCamera (this function is called when camera initialization is complete), onInit (called during initialization of the Web App), and onDone (called when the verification is complete). Most of these provide access to the job object of type Job, which contains useful information such as job.id, job.token, job.result.success, and job.status.
Arguments
| Parameters | Type | Description |
|---|---|---|
publicKey | string | Public key (Required). Deprecated alias: appId |
type | string |
|
token | string | Time-limited session token used to restart a session. Tokens are valid for 15 days. |
crossDevice | boolean |
|
crossDeviceQRCode | boolean |
|
crossDeviceSMS | boolean |
|
crossDeviceURL | string | Option to set a custom domain for cross device handoff.
|
showUploadFirst | boolean |
|
face | string |
|
id | string |
|
idLiveness | string |
|
liveness | string |
|
enableEyeCheck | boolean |
|
properties | array | Arbitrary properties to add to the job. Array of objects with name and value parameters.
|
| content | object | Properties to change the text content during the verification process. |
| verification | object | Optional verification properties. |
callbackURL | string | Upon the job's completion, Vouched will POST the job results to this URL. See webhooks for more info. |
| stepTitles | object | Titles for steps of the verification process. |
| theme | object | Change the theme and styles of the plugin. |
includeBarcode | boolean |
|
includeBackId | boolean |
|
disableCssBaseline | boolean |
|
onSubmit | function: | Javascript callback when a user submits a photo |
onCamera | function: | Javascript callback when camera initialization is complete |
onCameraEvent | function: | Javascript callback when there are changes to the Camera DOM element. |
onInit | function: | Javascript callback during initialization of the web app |
onDone | function: | Javascript callback when a verification is complete |
onReverify | function: | Javascript callback when a reverification job is complete |
onConfirm | function: | Javascript callback after user confirmation. See userConfirmation |
onSurveyDone | function | Javascript callback when a survey is complete. Contact[email protected] |
showProgressBar | boolean |
|
numForceRetries | number |
|
| handoffView | object | Settings for displaying the QR code when Mobile Handoff is enabled. |
locale | string |
|
enableGeoLocation | boolean |
|
| userConfirmation | object | Properties used for the user confirmation feature. |
manualCaptureTimeout | number |
|
manualCaptureTimeoutFace | number |
|
| digitalId | object | Options for enabling the mobile driver's license (mDL) verification flow. When enabled, users are presented with a Digital ID provider selection screen, allowing them to verify using a digital credential instead of photographing a physical ID. |
content Object
Optional properties to change the text content during the verification process.
| Property | Type | Description |
|---|---|---|
success | string | The messages posted after successful submission. Example: 'Please close this window to return your online visit.' |
review | string | Response to the user describing review of results. Example: 'Thank you for providing your information. We will review and get back to you.'. |
crossDeviceSuccess | string | Message posted after the crossDevice verification success. Example: 'Verification is complete, continue on your desktop.'. |
crossDeviceInstructions | string | Instructions and requirements for crossDevice. Example: 'We need to verify your identity. This requires government-issued photo ID as well as selfie. Please follow the instructions below to continue the verification process on your phone:' 1. Open the Camera App from your phone. 2. Hold the device so the QR Code appears in the viewfinder. 3. Click on notification to open the verification link. |
crossDeviceTitle | string | Title for crossDevice. Example: 'Identity Verification'. |
crossDeviceShowOff | boolean | If set to true, an option is displayed on the Handoff screen that allows the user to continue on Desktop, if set to false, this option will not be shown. |
crossDeviceQRInstructions | string | Instructions displayed on the QR code cross-device handoff screen. |
upperStartInstructions | string | Upper Instructions on Start Screen. |
middleStartInstructions | string | Middle Instructions on Start Screen. |
upperIdInstructions | string | Upper Instructions on ID Screen. |
lowerIdInstructions | string | Lower Instructions on ID Screen. Example: "You can either upload a photo you've already taken, or take a photo of your ID now.". |
upperBackIdInstructions | string | Upper Instructions on Back ID Screen. |
lowerBackIdInstructions | string | Lower Instructions on Back ID Screen. |
upperFaceInstructions | string | Upper Instructions on Face Screen. |
lowerFaceInstructions | string | Lower Instructions on Face Screen. |
lowestFaceInstructions | string | Lowest Instructions on Face Screen. |
upperIdCapturedInstructions | string | Upper Instructions on ID Captured Screen. |
middleIdCapturedInstructions | string | Middle Instructions on ID Captured Screen. |
middleBackIdCapturedInstructions | string | Middle instructions on ID Captured Screen when Barcode scan is enabled. |
lowerIdCapturedInstructions | string | Lower Instructions on ID Captured Screen. |
cameraIDButton | string | String text for camera button on ID Screen. |
| cameraButtonLabelUploadId | string | String text for Upload button on ID Screen. |
cameraFaceButton | string | String text for camera button on Face Screen. |
| cameraButtonLabelUploadFace | string | String text for Upload button on Face Screen. |
upperSuccess | string | Success message at the top. Example: 'Your photo uploads are complete!'. |
lowerSuccess | string | Success message at the bottom. Example: 'Thank you.'. |
upperFailure | string | Failure message at the top. Example: 'Try Again'. |
lowerFailure | string | Failure message at the bottom. Example: "The photo you shared can't be used for validation. Please take another picture, making sure the image of your face or your ID is clear.". |
verifyPass | string | The verification passed. Example: 'Everything looks good to us. Check your information and click next.'. |
verifyFail | string | The verification failed. Example: "We couldn't verify you. If you disagree, update your information and click next.". |
qrHandoffInstructions | string | Optional bottom Handoff Instructions. |
qrDesktopInstructions | string | Instructions for crossDeviceShowoff. qrDesktopInstructions is the instructions and requires '{qrDesktopLink}' to be set to inject text for the link. Default: 'Alternatively, you can {qrDesktopLink} if you have a good desktop camera.'. |
qrDesktopLink | string | String text used in qrDesktopInstructions to replace {qrDesktopLink}. qrDesktopLink becomes the link text. Example: Continuing the example above, if qrDesktopLink = 'continue', qrDesktopInstructions becomes 'Alternatively, you can continue if you have a good desktop camera.'. |
startCompanyInstructions | string | Optional Start Screen Instruction. |
carouselCompanyText | string[] | Array of strings where string at each index make up the Carousel Slide. |
carouselCompanyImg | string[] | Array of strings (image URL) where image at each index make up the Carousel Slide. |
progressIndicatorLoading | string | String that would replace term 'loading' in the Progress Indicator. |
progressIndicatorVouching | string | String that would replace term 'vouching' in the Progress Indicator. |
| upperProgressIndicatorId | string | String that would replace the upper text on ID processing progress screen on Avant theme |
| lowerProgressIndicatorId | string | String that would replace the lower text on ID processing progress screen on Avant theme |
| upperProgressIndicatorFace | string | String that would replace the upper text on Selfie processing progress screen on Avant theme |
| lowerProgressIndicatorFace | string | String that would replace the lower text on Selfie processing progress screen on Avant theme |
startScreenButtonLabel | string | Optional string to override the button text in the Avant Start screen. |
startScreenSelfieButtonLabel | string | Optional string to override the button text on the Start screen in the selfie-verification flow (e.g. 'Verify with a photo of the patient'). |
mobileDriversLicenseButtonLabel | string | Optional string to override the label for the mobile driver's license button. |
cameraTopIDDirections | string | Optional string to override the top text in the Avant ID Camera screen. |
cameraTopBackIdDirections | string | Optional string to override the top text in the Avant Back ID Camera screen |
cameraTopFaceDirections | string | Optional string to override the top text in the Avant Face Camera screen. |
cameraButtonLabelContinueSelfie | string | Optional string to override the button text in the Avant ID Captured screen. |
retryMessageInvalidIdPhoto | string |
|
retryMessageInvalidUserPhoto | string |
|
cameraScreenLabelFrontId | string | Optional prop to override the initial camera labels in the FrontID Camera Screen. |
cameraScreenLabelBackId | string | Optional prop to override the initial camera labels in the BackID Camera Screen. |
cameraFaceLabelShowFace | string | Optional prop to override the initial camera labels in the Face Camera Screen. |
mobileHandoffDoneMessage | string | Optional prop for extra text on the Done Screen when doing Handoff on Mobile. |
| surveyButtonLabel | string | String text for submit button on Survey Screen. |
| retryInstruction | string | Generic instructional text when the ID step fails and a new document capture is requested. |
| retryInstructionsDocumentNotPermitted | string | Instructional text displayed when the ID step fails due to non-permitted document type |
| retryMessageRestrictedDocument | string | Header text displayed when the ID step fails due to account configuration for ID constraints |
| restrictedDocumentMessages | string | Header text displayed when the ID step fails due to account configuration for ID constraints |
| documentTypeNotPermitted | string | Header text displayed when the ID step fails due to account configuration for ID constraints |
| documentNotPermittedByCustomer | string | Instructional text displayed when the ID step fails due to account configuration for ID constraints |
verification Object
Optional verification properties.
| Property | Type | Description |
|---|---|---|
firstName | string | Used to compare to the first name extracted from the ID document during Identity Verification.
|
lastName | string | Used to compare to the last name extracted from the ID document during Identity Verification.
|
birthDate | string | Used to compare to the date of birth extracted from the ID document during Identity Verification. Formats we accept
|
email | string | Used for identity Crosscheck. |
phone | string | Used for identity Crosscheck. |
enableIPAddress | boolean | Enable IP address check. This is a paid feature, reach out to[email protected] before turning on |
enablePhysicalAddress | boolean | Enable physical address check. This is a paid feature, reach out to[email protected] before turning on |
enableCrossCheck | boolean | Enable phone, email, and address Crosscheck. This is a paid feature, reach out to[email protected] before turning on |
enableDriversLicenseValidation | boolean | Enable Driver License Verification check on the ID. This is a paid feature, reach out to[email protected] before turning on |
enableDarkWeb | boolean | Enable dark web check. This is a paid feature, reach out to[email protected] before turning on |
internalId | string | An internal identifier for the verification within your organization. If provided it must be unique within your account or specific account group. Maximum length is 255 characters. |
crosscheckReferenceId | string | Reference ID for NIST IAL2 compliance verification. |
stepTitles Object
Titles for steps of the verification process.
| Property | Type | Description |
|---|---|---|
FrontId | string | The message shown on the ID screen. Example: "Front ID". |
Face | string | The message shown on the face screen. Example: "Face". |
Done | string | The message shown on the completion screen. Example: "Done verifying". |
IDCaptured | string | The message shown on the ID Captured screen. |
FaceCaptured | string | The message shown on the Face Captured screen. |
FullId | string | The message shown on the Full ID screen. |
Start | string | The message shown on the Start screen. |
BackId | string | The message shown on the Back ID screen. |
DigitalId | string | The message shown on the Digital ID screen. |
ExplicitConsent | string | The message shown on the Explicit Consent screen. |
theme Object
The theme object customizes the appearance of the JS Plugin. This includes setting colors, font styles, layout configurations, and more.
| Property | Type | Description |
|---|---|---|
name | string | Specifies the JS Plugin theme to use.
|
iconLabelColor | string | Hex value for Icon Label color. Compatible with theme: verbose Example: '#413d3a'. |
bgColor | string | Hex value for Background color. Compatible with theme: verbose
|
logo | object | Logo. Compatible with theme: verbose, avant Example: \ |
navigationActiveText | string | Hex value for navigation active text. Compatible with theme: verbose Example: '#413d3a'. |
iconColor | string | Hex value for Icon color. Compatible with theme: verbose Example: '#f6f5f3'. |
iconBackground | string | Hex value for Icon Background color. Compatible with theme: verbose Example: '#c8ae8f'. |
baseColor | string | Hex value for primary color. Compatible with theme: verbose, avant Example: '#4d7279'. |
fontColor | string | Hex value for font color. Compatible with theme: verbose Example: '#413d3a'. |
font | string | Font Family. Compatible with theme: verbose, avant Example: 'Open Sans'. |
navigationActiveBackground | string | Hex value for background color of active breadcrumbs. Compatible with theme: verbose Example: '#bacbd1'. |
navigationDisabledBackground | string | Hex value for background color of disabled breadcrumbs. Compatible with theme: verbose Example: '#bacbd1'. |
navigationDisabledText | string | Hex value for text color on disabled breadcrumbs. Compatible with theme: verbose Example: '#4d7279'. |
secondaryButtonColor | string | RGB value for color of the secondary buttons (Grey Retry Next button). Default: 'rgb(216, 216, 216)'. |
handoffLinkColor | string | Hex value for text color in the Mobile Handoff verification link. Default: '#40a1ed'. |
progressIndicatorTextColor | string | Hex value for text color of the progressIndicator in Avant theme. Default: '#000'. |
| common | object | This commonobject within the parent themeobject is responsible for applying styles to all global components used throughout the plugin. |
theme.common Object
The common object provides global styles that apply across all plugin components. This includes styling for containers, typography, layout, and common interactive elements such as Inputs and Buttons.
Note: All common components have a nestedstyle object for CSS to be added.
| Property | Type | Description |
|---|---|---|
container | object | Targets the main container of the plugin, setting general layout styles. This supports nested styles to control positioning, spacing, or responsiveness.
|
layout | object | Configures the layout styling, including header, body, and footer sections within the plugin. Use this to control each section's margins, paddings, and alignments.
|
layout.header | object | Controls the header section of the plugin globally across all screens. Use this to control the top section of the plugin (margin, padding, colors, etc..).
|
layout.body | object | Controls the body section of the plugin globally across all screens. Use this to control the mid section of the plugin (margin, padding, colors, etc..).
|
layout.footer | object | Controls the footer section of the plugin globally across all screens. Use this to control the main action area across all screens.
|
font | object |
url is optional but must be provided if not using a system font. |
headings | object | Set global styles for all headings across the plugin.
|
buttons | object | Set global styles for all buttons across the plugin.
|
inputs | object | Set global styles for all inputs across the plugin.
|
dropdowns | object | Set global styles for all dropdowns used in the plugin.
|
handoffView Object
Settings for displaying the QR code when Mobile Handoff is enabled.
| Property | Type | Description |
|---|---|---|
qRCodeSize | number |
|
onlyShowQRCode | boolean |
|
deviceCard | boolean |
|
styles.title | object | Sets styles for the headline text on the Handoff Screen. |
styles.description | object | Sets styles for the body text on the Handoff Screen |
styles.crossDeviceImage | string | Uses image url to add an image to the Handoff Screen. |
styles.button | object | Controls the styles for the Handoff Screen button |
styles.optionCard | object | Set styles for the handoff cards. Note: this requires deviceCard to be enabled. |
styles.optionCard.title | object | Set styles for the titles within the option cards on the Handoff Screen. |
styles.optionCard.description | object | Set styles for the description text within the option card on the Handoff Screen. |
reverificationParameters Object
Settings for Reverification (if enabled).
| Property | Type | Description |
|---|---|---|
jobId | string | The ID of the completed source verification job to reverify against. |
match | string | Default: selfie Enums: id, selfie. Matches the captured image to either the source job's ID image or Selfie image. |
internalId | string | The optional internalId you provided in the Verification Object. Can be used instead of the jobId. Only one reference ID should be provided. |
userConfirmation Object
Settings for user confirmation of photos (if enabled).
| Property | Type | Description |
|---|---|---|
confirmData | boolean | Shows the user the extracted data after ID photo is processed. |
confirmImages | boolean | Shows the user each photo taken before photo is processed. |
digitalId Object
Options for the mobile driver's license (mDL) verification flow.
| Property | Type | Description |
|---|---|---|
enabled | boolean | When true, presents users with a Digital ID provider selection screen before the standard ID capture step. Users can verify using a supported digital credential (e.g. a state-issued mobile driver's license) instead of photographing a physical ID. |
Unmount JS Plugin
vouched.unmount('#vouched-element')