## Overview
ZignSec’s ID and Biometric Verification service provides a secure and efficient way to verify identities, validate documents, and ensure compliance with regulations. With global support for over 14,000 identity documents, the service also includes optional age verification through biometric liveness detection, making it ideal for industries that require strict age controls.
Key features include:
- **Document Verification:** Analyze and authenticate passports, driver’s licenses, and other ID types.
- **Liveness Detection:** Verify users' presence and ensure they meet age requirements in real time.
- **Flexible Integration:** Use via a web interface, API, or (coming soon) mobile SDK.
- **Efficient Results:** Receive instant verification outcomes through webhooks or APIs.
ZignSec’s solution is designed to streamline onboarding, reduce fraud, and provide reliable identity and age verification for a variety of business needs.
### Ways of integrating ID and Biometric Verification
- Web (or browser) Flow is the most common way to use ZignSec UI and integrate it in your website (will be described in this document)
- API flow is suitable for advanced integration cases where merchant wants to fully control the UI
- Mobile SDK is in the roadmap
## Usage
### Document Analysis
The simplest use case for the scanning product – check user document. We provide the following:
- **Capture**
- Document capture or upload (configurable)
- **Analysis**
- Image quality assessment
- Support for 1- and 2- sides documents
- Document type detection
- Document OCR
- **Verifications**
- Different scenarios supported, the main used are:
- FullProcess
- Visual zone OCR
- Document type identification
- MRZ OCR
- Barcode recognition
- Document location
- Graphics cropping
- FullAuth
- FullProcess +
- Checking security features
- **Document acceptance**
- We can configure documents and types we accept based on
- Verification results
- And configurable rules
- **Results**
- Sent via webhook
- And available via GET endpoint
Document check is designed for identity verification services that specialize in reading and digital verification of passports, ID cards, driver's licenses, visas, and other identity documents. It‘s offering an automatic document type detection against a database of supported IDs. We have global ID coverage with full data page processing: MRZ and Visual inspection zones, and Barcode verification. It accelerates customer onboarding with seamless and secure ID verification that covers more than 14,000 identity documents for 250 countries and territories. You can get the whole list of supported documents from our [support team](mailto:
[email protected]).
The diagram below shows the user flow for session with the only document analysis requested. It shows QR code in the beginning as it’s recommended to use a phone camera to pass the flow. Depending on the configuration it allows to use camera or upload files from the file system.
**When flow is completed**
- User is redirected to the target url (redirect_success if flow passed or redirect_failure in case of error)
- Session is updated (so you can get the results using GET endpoint)
- And webhooks are sent
![[Document analysis session flow.jpg]]
**Figure 1: Document analysis session flow**
Depending on the user choice cancel behaviour varies, and it’s shown on the following diagram:
![[Document analysis session flow - Dealing with Cancellation.jpg]]
**Figure 2: Document analysis session flow - Dealing with Cancellation**
#### Document Analysis – UI
Below you can see a simple flow of online ID scanning, multiple options are available, like scanning your ID through browser or mobile, through QR code or getting link sent to your computer. Uploading a file from Gallery or Camera, choose the document type.
The generated session creates a URL that has multiple options to upload the identity document available to the user. When opened on desktop browser, the user can continue with the flow on desktop, can scan a QR code or send URL to a mobile number to continue on their phone. When opened on mobile the UI will proceed to document capture flow immediately. (Figure 5.)
The screens below illustrate an example of the session started on desktop (Figure 3), but QR code scanned (Figure 4) and document captured on mobile (Figure 5). It’s highly recommended to use a phone camera to capture documents due to higher quality of the images on average.
![[Start the ID verification process (Desktop).png]]
**Figure 3: Start the ID verification process (Desktop)**
![[QR code scanned (Desktop).png]]
**Figure 4: QR code scanned (Desktop)**
There are two main ways of uploading the document to ZignSec for processing:
- From camera
- Automatic
- Manual
- From gallery
The upload from camera connects to the default camera of the device (user has to give permissions in the browser) and allows the user to take images of their identity documents either in automatic or manual mode.
Automatic mode works on real-time recognition of the document and takes photo(s) of the document automatically. In manual mode the user must press a button to take a photo.
Both ways end with document Preview to enable the user to review the images sent to ZignSec for processing.
The upload from gallery opens the files directory of a device for user to select the file.
We recommend using automatic document capture from camera to ensure the best performance and restrict the ability to upload fraudulent images and/or processing irrelevant images/information.
![[Capture document (on mobile).jpg]]
**Figure 5: Capture document (on mobile)**
When document is successfully processed a “Thank you” page is shown on mobile (Figure 6), and the session will be finalized on the primary device (desktop in our example).
![[Thank you page (mobile).jpg]]
**Figure 6: “Thank you” page (mobile)**
When the session is successfully finished (meaning we processed the document and issued any final result)) the user is redirected to the redirect_success url set during session creation (or in the merchant settings for your API key). If it’s not set the “Thank you” page is shown (Figure 6).
By default, the system is set up to prompt the customer to retry document verification in case of a negative result to improve the conversion. In this setup, the redirect_success will only be reachable if the document processing is successful.
![[Thank you page (Desktop) 1.png]]
**Figure 7: “Thank you” page (Desktop)**
An alternative way is to upload files from gallery (Figure 8).
![[Document upload UI.jpg]]
**Figure 8: Document upload UI**
### Document + Biometric Analysis
This scenario extends the first one with biometric analysis. When the document is accepted on the first step, we can ask the user to pass the biometry check (liveness or selfie depending on the configuration). During the biometric check we run the face match analysis to match the faces from the document with the portrait captured during the biometric check and accept session if the match level is within the configured range.
To pass a face match user must:
1. Pass the document check (we do not run biometry analysis if document is not accepted)
2. Pass the liveness check (also available independently) that confirms the authenticity of the person
3. Or just capture a selfie (upload is also possible but not recommended)
#### Liveness Detection
Liveness detection technology streamlines remote biometric verification and efficiently prevents fraudulent presentation attacks such as the use of static face images with or without electronic devices, printed photos, video replays, video injections, or realistic masks instead of a real person. It instantly determines spoofing attacks with live face substitutes while verifying identity through the smartphone camera or desktop device.
It combines various techniques like texture analysis, depth and shape of an image, facial movement, and other factors to determine whether it is a real live person or a fake representation.
The system chooses 4 random directions out of 8 positions on a circle for the user to perform during the liveness check, creating 4,096 unique combinations that are virtually impossible to circumvent by pre-recording and injecting a video.
In addition to identity verification, liveness detection also enables age verification by ensuring the user is physically present and validating their facial features against age-estimation algorithms.
#### Selfie Capture
When liveness is not necessary, a simple selfie capture can be used to take a user photo.
The flow can be resumed in the activity diagram below (if flow is configured to just use selfie – the liveness analysis will be replaced with the selfie capture.)
![[Document + Liveness check 1.jpg]]
**Figure 9: Document + Liveness check**
#### Document+Liveness UI
> [!NOTE]
> It’s highly recommended to use a phone camera to capture documents and selfie or pass the liveness check.
The document analysis UI is same (Figures 3-5), but instead of the thank you page the flow is continued with Selfie capture or Liveness UI is shown on the Figure 10 (it’s set in the session request or in the merchant configuration for your api key which one to use).
Both wizards will guide a user through the capture process, but liveness will require user to perform 4 additional actions (i.e. “Turn your head a bit”).
![[Liveness check UI 1.jpg]]
**Figure 10: Liveness check UI**
### Customization Possibilities
The flow is configurable (the order is fixed as we need to show welcome screen with the possibility to scan QR code and switch to mobile, then we can upload files and analyze uploaded documents, and run a biometry check afterwards) using the following steps:
![[A screenshot of a qr code.png]]
- Welcome / Continue on phone
![[A screenshot of a upload card.png]]
- Select document type to upload
![[A screenshot of a document type.png]]
- Upload ID document
![[Liveness check UI 1.jpg]]
- Biometry
- Liveness check or
- Selfie check
- Upload a file: possibility of uploading from the local disk or capturing an image through camera.
The flow configuration is done by our support team, please also contact support if you want to send flow configuration on every request yourself.
#### Document Analysis
The main customization possibilities are described in this document, please contact our support if you need more to cover your business case.
##### Filter Document Types
Document types can be limited as per your business requirements, for instance to accept only passports and ID cards issued by the configured countries.
##### Retry Policy
Retry option is useful in capturing the document or the face again when the first attempt got declined. It makes the end user win time and easily comply with the image quality requirements. You can read more about image quality requirements in the “Ref C” section (see References).
![[Document+Liveness check with retry.jpg]]
**Figure 11: Document+Liveness check with retry**
_DOCUMENT ANALYSIS WITH RETRY – UI_
The main UI is similar to Figures 3-5
If retry is turned on, and document analysis **DECLINED**, the user is asked to capture the id document again.
![[Retry scenario.png]]
**Figure 12: Retry scenario in case the document get declined**
##### Choose Proper Scenario
We can help you define which scenario suits you best for document analysis. The most used two are **FullAuth** or **FullProcess**. The only difference in these 2 scenarios is that the **FullAuth** runs security checks (UV dull paper check, image patterns (VIS), IR transparency, etc.), it’s longer to run, it’s more demanding on camera/picture quality, and has a lower overall acceptance rate.
In most cases **FullProcess** is recommended unless there is a need for the security features.
#### Face Match Analysis
This analysis compares a face picture taken from liveness or from selfie capture to the portrait existing in the document.
##### Customize Thresholds
We can configure a threshold for FaceMatch analysis to be **Accepted** (The analysis will be **Accepted** if similarity is equal or above this threshold). Or you can choose to set it to be **OperatorRequired** (The analysis will be **OperatorRequired** if similarity is equal or above this threshold and less than acceptanceThreshold)
#### UI
In addition to different settings of the UI components the following parts are customizable:
##### Custom Themes
You can choose 'light' or 'dark' theme, according to the scheme on your website. For more configuration our support team can give you a CSS file with an example of styles customization.
![[Dark vs Light theme.jpg]]
**Figure 13: Dark vs Light theme**
##### Localizations / Custom Texts
We already support 10 languages (please find the list of supported languages below), to add support for a new language send a request to our support and provide translations for the texts they send you in response. It usually takes from 2 (for languages listed in Ref A) to 4 weeks to add a new language when all translations are provided.
As for now we support the following languages:
- Czech (cs),
- English (en),
- French (fr),
- German (de),
- Greek (el),
- Italian (it),
- Russian (ru),
- Spanish (es),
- Swedish (sv),
- Turkish (tr)
##### Use From Iframe
The flow url returned upon session creation can be opened from iframe, please find technical details in the Ref B – iframe events.
#### Customize file pload
##### Force Camera Usage
It’s recommended to force users to use their phone camera to capture a document picture, but it’s also possible to allow file upload from the device.
##### Allowed File Extensions
By default. we do not restrict file types on upload, and the analysis service supports JPEG, PNG, TIFF image formats. But it’s possible to configure a file type filter by setting allowed file extensions.
## Core Functionalities
### Environments
We maintain environments you can use:
**Test** **(TEST)** **Environment**: `https://test-gateway.zignsec.com/api/v5/sessions/scanning-dp50/`
**Production** **(PROD)** **Environment:** `https://gateway.zignsec.com/api/v5/sessions/scanning-dp50/`
### Authentication
Each request to our API should be authenticated by sending your subscription key in the “Authorization” header. Our support creates subscription keys for you (a pair for each environment), and it’s highly recommended to regularly rotate the keys (currently it’s done by sending a support request, but please let us know if you’d like to automate it).
If you need different configurations it’s possible to register multiple tenants and configure them differently.
### REST API
#### Headers
| | | |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| **Header** | **Description** | **Required** |
| Authorization | This header parameter is the subscription key you received from ZignSec during the registration process. Example: Authorization: 123456add0cff22873c428e987654321 | Yes |
| Content-Type | Specifies the media type of the request body data. Set to application/json if JSON object. | Yes |
OpenAPI specification and documentation
##### Live Documentation
[https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/](https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/)
##### OpenAPI Specification
It’s recommended to use REST client code generation from the openapi specification: [https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/scanning-dp50.json](https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/scanning-dp50.json)
##### Recommended Client Code Generation Tools
For .NET we recommend NSwagStudio ([https://github.com/RicoSuter/NSwag](https://github.com/RicoSuter/NSwag)), for other stacks – OpenAPI Generator ([https://github.com/OpenAPITools/openapi-generator,](https://github.com/OpenAPITools/openapi-generator) [https://github.com/OpenAPITools/openapi-generator-cli](https://github.com/OpenAPITools/openapi-generator-cli))
#### Examples:
Link to Postman collection in JSON: [Link](https://25357801.fs1.hubspotusercontent-eu1.net/hubfs/25357801/Support%20Files/ZignSec%20-%20Scanning%20Examples.postman_collection.json)
#### API Endpoints
##### Create Session
POST /api/v5/sessions/scanning-dp50/web - [https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/#/BrowserFlow/CreateSession](https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/#/BrowserFlow/CreateSession)
##### Get Session Details (Default, Lite Version)
GET /api/v5/sessions/scanning-dp50/{sessionId} - [https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/#/ApiFlow/GetSession](https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/#/ApiFlow/GetSession)
A big portion of the full session response is not used in most cases, so we return a smaller response with the main details by default
##### Get Session Details (Full Response)
GET /api/v5/sessions/scanning-dp50/{sessionId}/details - [https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/#/ApiFlow/GetSessionWithDetails](https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/#/ApiFlow/GetSessionWithDetails)
##### Webhooks
Every time session state changed, we send a webhook (see our common Webhook documentation), with the structure described in the live documentation:
[https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/#/callbacks/Scanning_Callbacks_SessionEvent](https://gateway.zignsec.com/api/v5/openapi/scanning-dp50/#/callbacks/Scanning_Callbacks_SessionEvent)
NOTE: by default, the lite version is sent, please send a request to our support team if you’d like to receive full session details
### Session State
#### DTO Overview
Session state is described by ScanningSessionData data transfer object (dto).
![[Session state.png]]
**Figure 14: Session state**
#### Session Status
The following state chart diagram shows session statuses
![[Session status.png]]
**Figure 15: Session status state chart diagram**
### Session Result
Scanning session is a flow instance, with 0 or more analyses executed. Session status is recalculated after each session event and is driven by the flow and analyses results. Every single analysis has its own status.
Scanning session result describes
- Document analysis result – See below for more details
- Detected identity details
- available in local language (response field: “identity”)
- and international version (response field: “identity_english”)
- Liveness analysis details – “status” field is mainly describing the analysis status (it’s true for all other analyses) also contains **estimated age of person**
- Face match analysis details – “status” shows analysis result, “similarity” shows the minimal similarity found among the compared images (see userImages field)
- Documents uploaded to the session
#### Document Analysis Result
The main analysis result is in the “status” field, like for other analyses.
- “textResult” – shows the OCR result – parsed fields, for each field – detected field type, the value source(s), the probability (for the whole value, and for each individual recognized symbol), and status of the cross-value checks (for instance if value is present in visual field and in MRZ, cross- check is done)
- “summary” contains details of the different analysis steps/parts, useful for troubleshooting DECLINED analyses
- “opticalStatus” shows if the image is optically recognized
- “opticalDetials” shows detailed checks – document type, image quality, security checks, text recognition, mrz recognition; shows the document page count (“pagesCount”)
- and overall result from provider (“overallStatus”)
- “images” contains images for the recognized document parts (i.e. Portrait or Signature)
- “identity”/”identity_english” – identity recognized from the document
- “documentType” – information about detected document type
### Examples
Please find examples in the ZignSec – Scanning 5.1 postman collection (available on the docs site or our support can share it by request).
## References
### Ref A – Languages already supported by UI components
The following languages already supported by the UI components, adding support for one of the listed languages requires less texts to translate and takes less time.
| | | | |
|---|---|---|---|
|Arabic (ar)|Croatian (hr)|Norwegian (nb)|Thai (th)|
|Bangla (bn)|Hungarian (hu)|Dutch (nl)|Ukrainian (uk)|
|Danish (da)|Indonesian (id)|Polish (pl)|Vietnamese (vi)|
|Finnish (fi)|Japanese (ja)|Portuguese (pt)|Chinese Simplified (zh-Hans)|
|Hebrew (he)|Korean (ko)|Romanian (ro)|Chinese Traditional (zh-Hant)|
|Hindi (hi)|Malay (ms)|Slovak (sk)||
### Ref B – iframe events
#### Code snippet for testing
```html
<!DOCTYPE html>
<html lang="en">
<head>
</head>
<body>
<!-- Our iframe docs: https://docs.zignsec.com/faq/apioverview/scanning-javascript-events-withpostmessage/ -->
<iframe src="" style="width: 600px; height: 600px"></iframe>
<script>
window.addEventListener(
"message",
(event) => {
// NOTE: Allowed origins can be configured via merchant settings (please contact the support team) // If not configured, "*" will be used as targetOrigin to postMessage
// https://developer.mozilla.org/enUS/docs/Web/API/Window/postMessage#security_concerns
if (event.data.product !== "SCANNING") return;
console.log(event.data);
const payload = event.data.payload;
const { sessionId, sessionStatus, relayState, errorCode, errorDetails } = payload;
if (errorCode) {
// handle error
console.error(payload);
} else {
// handle success
console.log(payload);
}
},
false
);
</script>
</body>
</html>
```
#### iframe event examples iframe event types
- target
- targetError
- secondaryDeviceConnected
- secondaryDeviceDisconnected
#### iframe event examples
#### target
```json
{
"product": "SCANNING", "payload": {
"relayState": "12345",
"sessionId": "62fe7465-309d-4591-9ae3-8ed28de46261", "sessionStatus": "Accepted",
"type": "target"
}
}
```
#### targetError
```json
{
"product": "SCANNING", "payload": {
"errorCode": "CANCELED_BY_USER", "errorDetails": "Action canceled by user", "relayState": "12345",
"sessionId": "67252982-0152-4755-8530-dab68075e3fd",
"sessionStatus": "Cancelled", "type": "targetError"
}
}
```
#### secondaryDeviceConnected
```json
{
"product": "SCANNING", "payload": {
"type": "secondaryDeviceConnected",
"sessionId": "67252982-0152-4755-8530-dab68075e3fd",
"relayState": "12345", "sessionStatus": "GeneratedLink"
}
}
```
#### secondaryDeviceDisconnected
```json
{
"product": "SCANNING", "payload": {
"type": "secondaryDeviceDisconnected",
"sessionId": "67252982-0152-4755-8530-dab68075e3fd",
"relayState": "12345", "sessionStatus": "GeneratedLink"
}
}
```