Overview
This document describes the Document Verification feature of the Instnt platform. The document verification feature is only available if your customer onboarding workflows require document verification and if you have enabled Document Verification in the Instnt Dashboard Business Rules Configuration section for your customer sign-up workflow.
Upload and verify government-issued identification documents such as Driver's Licenses, passports, and more. Document uploading is a multi-step process when using our API. When using the SDK, follow the respective SDK documentation to integrate the document verification in your sign-up workflow. See the Quickstart guide for more information on how to use our sandbox environment.
Document verification prerequisites
- Document verification is available on mobile-reactive web apps, iOS, or Android apps.
- iOS and Android mobile devices with Chrome or Safari browsers are supported.
- Desktop devices are unsupported due to incompatible embedded cameras and gyroscopes for orientation detection. Feature functionality may vary based on the browser.
- If you are using one of our web SDKs, do not include HTML tags with IDs containing the prefix 'aid.' E.g., <div id=’aidFooter'> in your web app as this prefix is reserved for the user by the toolkit.
Document Verification Workflow
Instnt now provides a set of web and mobile SDKs for the document verification integrated and REST API endpoints for the document verification process. Here is an overview of the process:
- Using one of our SDKs, you can provide an option to capture the documents to the user. Each SDK includes the interface to take a picture of the documents, upload them, and then initiate the verification process.
- Documents verified for quality such as clarity, sharpness, authenticity, resolution, etc. If quality standards do not meet, users are required to resubmit.
- Once your application obtains the documents, you can call Instnt SDK functions and upload the document directly to the Instnt cloud.
- For a driver's license, you can allow the user to capture both front and back images while only the front image is required. For passport verification, only the front information page is needed.
- Instnt provides a provision to capture and upload selfies for deeper verification following the same integration steps.
- Once required documents are uploaded, the SDK function to initiate the document verification process can be invoked.
- Your application receives a decision once evaluated.
Instnt SDKs emit events corresponding to each of these steps. For more details, see here.
Note: If you directly integrate with our APIs instead of our SDKs, you won't be able to use the document and selfie capture features. Instead, you can provide an alternative interface to capture/upload the document images to Instnt Cloud by calling the corresponding API endpoints directly.
SDK Functions and API endpoints
The first step with our SDKs is to initialize the camera to capture each document image. Such as the front and back sides of a driver's license. The same initialization steps follow for the capture of the selfie image. You must invoke the API for every document.
Whereas with our SDK, a single wrapper function covers both the API invocations.
Before performing the first step, you need to begin the transaction. The beginning transaction provides you the transaction ID that needs to pass in the subsequent SDK, including the API calls. For more information, see Instnt integration process.
Step 1: To obtain a pre-signed URL, invoke the endpoint or a function of an SDK below.
- uploadAttachment
- scanDocument
- scanDocument
- https://api.instnt.org/doc/swagger/#/transactions/transactions_attachments_create
Step 2: Invoke the pre-signed URL to upload the document in base64 encoded format.
Note: In the SDK, the above two steps bundle in just one function.
Step 3: After all of the documents are uploaded, initiate Document Verification by invoking the following endpoint.
Note: The third step only initializes the document verification. There is no immediate response but only an acknowledgment of the document verification.
- verifyDocuments
- verifyDocuments
- verifyDocuments
- https://api.instnt.org/doc/swagger/#/transactions/transactions_attachments_verify_create
You receive a final decision via a JSON Web Token (JWT) once you submit all the information to the Instnt Submit Workflow.
Document and Selfie Capture Settings
The capture setting is customizable based on your preference when you use Instant SDK to capture a document or selfie for verification.
The capture settings determine the thresholds and requirements for quality.
There are two types of settings for one of each scanning method exposed by the SDK. You can initialize these classes just like any others. The scan methods are DocumentSettings and SelfieSettings.
The recommended values are set as the default values for both classes. These do not need to change unless indicated otherwise.
There are only a couple that we recommend changing, see recommendations highlighted in the table below.
DocumentSettings Properties
Property Name |
Type |
Description |
autoCaptureCheckNFrames |
number |
The number of consecutive frames that must contain a good image before the image is captured. Increasing this number will result in the end-user needing to hold their device steady for longer, which should result in less blurry images being captured by the SDK. We recommend setting this to 2 for the fronts of documents and 3 for the backs of documents. default: 0 |
enableLocationDetection |
boolean |
When true, the SDK will prompt the user to grant location access. This is used to capture the lat/lon of the device when the image was captured. When false, the SDK will not prompt the user to grant location access and the lat/lon of the device when the image was captured will not be known. We recommend setting this value to true. default: false |
captureMode |
string |
Accepted Values
This property is only used when useNativeCamera = false We recommend setting this value to “Auto.” default: “Manual” |
backGlareThreshold |
number |
Captured images of the backs of documents must contain less than this amount of glare. If they do not, they are not considered good images. We recommend using 2.5 for this value. default: 0 |
documentSide |
string |
Accepted Values
default: “Front” |
documentType |
string |
Accepted Values
default: “License” |
useNativeCamera |
boolean |
When true, indicates that the device’s camera application should be used to capture the image. Because this is a separate app on the device that we have no control over, no visual feedback is given to the user in real-time while capturing the image. We evaluate the image once it is captured and sent back to the browser. When false, indicates that the browser application that is currently running should be used to capture the image. This experience will give the user visual, real-time feedback about whether or not the image contains an ID that meets minimum requirements. default: false |
backCaptureAttempts |
number |
The number of times the end-user should be prompted to recapture any bad images of the back of a document. Once this threshold is met, the image is accepted regardless of whether or not it actually meets minimum requirements. default: 4 |
backFocusThreshold |
number |
Captured images of the backs of documents must contain at least this much focus. If they do not, they are not considered good images. default: 40 |
enableFaceDetection |
boolean |
When true, images of the front of documents must contain a face to be considered a good image. When false, images that do not contain a face will still be counted as good images. The property is only used when documentSide = “Front” default: true |
frontCaptureAttempts |
number |
The number of times the end-user should be prompted to recapture any bad images of the front of a document. Once this threshold is met, the image is accepted regardless of whether or not it actually meets minimum requirements. This property is only used when useNativeCamera = false default: 4 |
frontFocusThreshold |
number |
Captured images of the fronts of documents must contain at least this much focus. If they do not, they are not considered good images. default: 40 |
frontGlareThreshold |
number |
Captured images of the fronts of documents must contain less than this amount of glare. If they do not, they are not considered good images. default: 2.5 |
isBarcodeDetectedEnabled |
boolean |
When true, images of the back of documents must contain a valid PDF417 barcode in order to be considered good images. When false, images of the back of documents do not have to have a barcode present to be considered a good image. This property is only used if documentSide = “Back” default: true |
licenseFaceDetectionProportionMax |
number |
The maximum proportion size of the faces in relation to the rest of the camera feed. This ensures that the document is not too close to the camera. This property is only used if documentType = “License”. default: 6 |
licenseFaceDetectionProportionMin |
number |
The minimum proportion size of the faces in relation to the rest of the camera feed. This ensures that the document is not too far away from the camera. This property is only used if documentType = “License”. default: 2.1 |
manualPostClickTimeout |
number |
The number of seconds after a tap/click when the SDK will search the video stream for a good image. If it does not find a good image, it will just choose the last one. This property is only used when useNativeCamera = false This property is only used when captureMode = “Manual” default: 4 |
nativeBackFocusThreshold |
number |
Images of the backs of documents captured by the native camera app must contain at least this much focus. If they do not, they are not considered good images. default: 0 |
nativeBackGlareThreshold |
number |
Images of the backs of documents captured by the native camera app must contain less than this much glare. If they do not, they are not considered good images. default: 0 |
nativeFrontFocusThreshold |
number |
Images of the fronts of documents captured by the native camera app must contain at least this much focus. If they do not, they are not considered good images. default: 0 |
nativeFrontGlareThreshold |
number |
Images of the fronts of documents captured by the native camera app must contain less than this much glare. If they do not, they are not considered good images. default: 0 |
overlayColor |
string |
The hex code for the color to be used for the overlay border. Include the “#” for the hex code, or be a CSS-supported color name (e.g. “red”, “blue”, “yellow”, etc.) default: yellow |
overlayOnClickTextManual |
string |
This string is displayed on the screen when an end-user taps to capture an image. This property is only used when captureMode = “Manual” This property is only used when useNativeCamera = false default: “Hold Steady” |
overlayText |
string |
This string is displayed on the screen when the SDK is launched and captureMode = “Manual” or when captureMode = “Auto” and setManualTimeout lapses and the SDK goes into manual capture mode. default: "Align ID and Tap Screen<br/> to Capture" |
overlayTextAuto |
string |
This string is displayed on the screen when the SDK is launched and captureMode = “Auto”. default: "Align ID within box and Hold" |
passportFaceDetectionProportionMax |
number |
The maximum proportion size of the faces in relation to the rest of the camera feed. This ensures that the document is not too close to the camera. This property is only used if documentType = “Passport”. default: 6 |
passportFaceDetectionProportionMin |
number |
The minimum proportion size of the faces in relation to the rest of the camera feed. This ensures that the document is not too far away from the camera. This property is only used if documentType = “Passport”. default: 2.1 |
setManualTimeout |
number |
The number of seconds after which the SDK will switch captureMode from “Auto” to “Manual” and prompt the user to tap to capture an image. This property is only used when captureMode = “Auto.” default: 15 |
showCaptureModeText |
boolean |
When true, the captureModeText string is shown at the top right of the capture overlay. When false, this string is not shown. default: false |
captureModeText |
string |
This string is shown at the top right of the capture overlay if showCaptureModeText = true. Use this property to designate which mode the capture experience was started in. default: null |
SelfieSettings Properties
Parameter Name |
Type |
Description |
autoCaptureCheckNFrames |
number |
The number of consecutive frames that must contain a good image before the image is captured. Increasing this number will result in the end-user needing to hold their device steady for longer, which should result in less blurry images being captured by the SDK. Note: We recommend setting this to 2 for selfies. default: 0 |
captureMode |
string |
Accepted Values
Note: We recommend setting this value to “Auto.” default: “Manual” |
enableFarSelfie |
boolean |
When true, the browser zooms in on the video stream, prompting the user to move the phone further away from their face. This does not change the resolution of the captured image, it only forces the user to move their device further from their face. This is called “a far selfie” or “a liveness selfie”. When false, no zoom is applied to the video stream. This property is only used when useNativeCamera = false Note: We recommend setting this value to true. default: false |
enableLocationDetection |
boolean |
When true, the SDK will prompt the user to grant location access. This is used to capture the lat/lon of the device when the image was captured. When false, the SDK will not prompt the user to grant location access and the lat/lon of the device when the image was captured will not be known. Note: We recommend setting this value to true. default: false |
useNativeCamera |
boolean |
When true, indicates that the device’s camera application should be used to capture the image. This is a separate app on the device that we have no control over, no visual feedback is given to the user in real-time while capturing the image. We evaluate the image once it is captured and sent back to the browser. When false, indicates that the browser application that is currently running should be used to capture the image. This experience will give the user visual, real-time feedback about whether or not the image contains a document that meets minimum requirements. default: false |
captureAttempts |
number |
The number of times the end-use should be prompted to recapture any bad images of their face. Once this threshold is met, the image is accepted regardless of whether or not it actually meets minimum requirements. default: 4 |
enableFaceDetection |
boolean |
When true, images of the user’s face must contain a face to be considered a good image. When false, images that do not contain a face will still be counted as good images. default: true |
farSelfieFaceDetectionPropo rtionMax |
number |
The maximum proportion size of a face in relation to the rest of the camera feed. This ensures that the user’s face is not too close to the camera. This property is only used if enableFarSelfie = true. default: 50 |
farSelfieFaceDetectionPropo rtionMin |
number |
The minimum proportion size of a face in relation to the rest of the camera feed. This ensures that the user’s face is not too close to the camera. This property is only used if enableFarSelfie = true. default: 30 |
goodImageFoundADA |
string |
When the SDK is used in a browser where ADA mode is enabled, this string will be read out to the end-user when a good image is detected by the SDK and it requires a tap to capture the image. This property is only used when useNativeCamera = false default: "Good Image Found" |
nearSelfieFaceDetectionProp ortionMax |
number |
The maximum proportion size of a face in relation to the rest of the camera feed. This ensures that the user’s face is not too close to the camera. default: 60 |
nearSelfieFaceDetectionProp ortionMin |
number |
The minimum proportion size of a face in relation to the rest of the camera feed. This ensures that the user’s face is not too close to the camera. default: 40 |
notGoodImageADA |
string |
When the SDK is used in a browser where ADA mode is enabled, this string will be read out to the end-user where a bad image has been captured by the SDK. This property is only used when useNativeCamera = false default: “Captured Image is not good” |
notificationADA |
string |
When the SDK is used in a browser where ADA mode is enabled, this string will be read out to the end-user when a good image has been captured by the SDK. This property is only used when useNativeCamera = false default: "Valid image selected" |
orientationErrorText |
string |
This string is shown on the overlay when an end-user is meant to be taking a selfie image but their device is in landscape mode. The SDK does not support taking selfie images in landscape mode. default: "Landscape orientation is not supported. Kindly rotate your device to Portrait orientation." |
overlayColor |
string |
The hex code for the color to be used for the overlay border. Include the “#” for the hex code, or be a CSS-supported color name (e.g. “red”, “blue”, “yellow”, etc.) default: yellow |
overlayText |
string |
This string is displayed on the screen when the SDK is launched and captureMode = “Manual” or when captureMode = “Auto” and setManualTimeout lapses and the SDK goes into manual capture mode. default: "Align Face and Hold" |
overlayTextAutoADA |
string |
When the SDK is used in a browser where ADA mode is enabled, this string will be read out to the end-user when the SDK is started. This property is only used when captureMode = “Auto” This property is only used when useNativeCamera = false default: "Align ID and hold till you hear notification" |
overlayTextAuto |
string |
This string is displayed on the screen when the SDK is launched and captureMode = “Auto”. default: "Align Face and Hold" |
overlayTextManualADA |
string |
When the SDK is used in a browser where ADA mode is enabled, this string will be read out to the end-user when the SDK is started. This property is only used when captureMode = “Manual” This property is only used when useNativeCamera = false default: "Align ID and click when you hear notification" |
setManualTimeout |
number |
The number of seconds after which the SDK will switch captureMode from “Auto” to “Manual” and prompt the user to tap to capture an image. This property is only used when captureMode = “Auto” default: 15 |
showCaptureModeText |
boolean |
When true, the captureModeText string is shown at the top right of the capture overlay. When false, this string is not shown. default: false |
captureModeText |
string |
This string is shown at the top right of the capture overlay if showCaptureModeText = true. Use this property to designate which mode the capture experience was started in. default: null |
useBackCamera |
boolean |
When true, the rear-facing camera is used to capture selfie images. When false, the front-facing camera is used to capture selfie images. |
cancelButtonText |
string |
This string is shown at the lower left of the capture overlay. When tapped by end-users, the SDK capture experience is aborted. default: “Cancel” |
photoLabelText |
string |
The string is shown on the capture overlay directly above the camera's white circle capture button, that users tap to capture selfie images. |
SDK Docs
For Instnt public API endpoints, see Instnt Swagger. For more information on full integration with your application, see Instnt Accept Integration.