Liveness is used to protect against biometric attacks. It’s a proof of a real person working on Id analysis, Face biometry verification and Liveness verification.
An active liveness check involves users performing fundamental movements to prove they are alive. This way, you detect presentation attacks like photo or video spoofing, deepfakes, models or 3D masks.
Swagger link:
Test: Swagger UI (zignsec.com)
Prod : Swagger UI (zignsec.com)
Flow
Step 1: Initialize scanning session
Note: Liveness is video based only and no audio is available.
Step 1.1: Create a new Browser flow (web flow) scanning session
POST to
Test environment: https://test-gateway.zignsec.com/core/api/sessions/identity_verification/liveness
Production environment: https://gateway.zignsec.com/core/api/sessions/identity_verification/liveness
Request example
POST https://test-gateway.zignsec.com/core/api/sessions/identity_verification/liveness
Content-Type: application/json
Authorization: 12345678-YOUR-ACCESS-TOKEN-5352305c9fb0
Content-Length: 725
{
"locale": "en",
"metadata": {
"locale": "en",
"options": "FrontAndBack"
},
"redirect_failure": "https://my_failure_url.com",
"redirect_success": "https://my_success_url.com",
"relay_state": "my-unique-customer-id",
"webhook": "https://my_webhook_url.com"
}
Step 1.2: Description of request model
locale | supports langauges like : en , se ,de , fr, gr, it ,ru ,es , cz, tr | required |
metadata | Contain parameters like:
| required |
options | [ FrontAndBack, NoDocument, FrontSide ] | |
redirect_success | If this parameter is supplied the browser session will finally be redirected to this URL-value (it’s applicable only if analysis with provider’s UI is used i.e. liveness) Example : "target": "https://landing.mysite.com" | Not required |
redirect_failure | target_error works as target except it is navigated on user cancel or error situations. | Not required |
webhook | A URL where success/error results will automatically be POST:ed. During test you try https://webhook.site/ for free webhook URLs. | Not required |
Step 1.3: Example of response for initializing scanning session
{
"data": {
"id": "51184044-036e-4d98-85ad-9e2c565a78a5",
"redirect_url": "https://test.zignsec.com/v3/scan/51184044-036e-4d98-85ad-9e2c565a78a5",
"status": "created"
}
}
Step 1.4: Description of response model
id | The session identifier, a GUID (globally unique identifier) unique for the started workflow, used both in the redirect_url and the get analysis results. |
errors | A JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair of parameters is returned for each error. code Code for the error. List of codes is in table below. description A string that describes the type of error that occurred. If no errors occur, then this object is empty. errors : [] |
redirect_url | The URL that the user need to be redirected to complete the data via the web interface. It is possible to load the URL in an iframe. |
status | Indicates whether the verification of the customer is completed or not. Possible values are
|
Step 2: Browser steps
There are two approaches to complete files upload to scanning:
- Browser flow
- Mobile flow
Step 2.1: Example of browser flow
Browser flow: Upload all images from current browser.
| Authenticate with your access token | Control your settings and Choose to scan through browser | Follow instructions 1- Make a photo of document’s front side | 2- Confirm and start face analysis =>Align your face with the frame | Waiting for Analyzing and Getting result (See details in the portal) |
 |  |  |  |  |
Step 2.2: Example of mobile flow
Mobile flow: start session in browser, continue in mobile, back to browser.
| Browser steps | |||||
| Authenticate with your access token | Control your settings and Choose to scan through mobile | Scan QR code by mobile and access the link | |||
| |  | |||
| Mobile steps | |||||
| Open link from QR code | Follow instructions 1- Make a photo of document’s front side | 2- Confirm and start face analysis =>Align your face with the frame | Waiting for Analyzing and Getting result (See details in the portal) | ||
 | | | | ||
Step 3: Get analysis result
GET to
Test Enviornment – https://test-gateway.zignsec.com/core/api/sessions/51184044-036e-4d98-85ad-9e2c565a78a5
Prod Enviornment – https://gateway.zignsec.com/core/api/sessions/51184044-036e-4d98-85ad-9e2c565a78a5
To get result of scanning you need to call API Get result.
Step 3.1: Example of GET response
{
"data": {
"request_data": {
"locale": "En",
"metadata": {
"locale": "en",
"options": "FrontAndBack"
},
"redirect_failure": "https://my_failure_url.com",
"redirect_success": "https://my_success_url.com",
"relay_state": "my-unique-customer-id",
"webhook": "https://my_webhook_url.com"
},
"analysis_details": [
{
"analysed_documents": [],
"analysis_id": 78679,
"document_analysis_details": {
"document_type": "Germany - Id Card (2010)",
"found_document_types": [
{
"document_type": "Germany - Id Card (2010)",
"file_name": "img-1.jpg",
"image_url": "https://test.zignsec.com/v3/scan/api/v1/images/1b28bd68-503b-4551-9151-c2d6969394d6/fc41c798-e361-474b-a3c5-a70175b4b222"
},
{
"document_type": "Germany - Id Card (2010-2021) Side B",
"file_name": "img-2.jpg",
"image_url": "https://test.zignsec.com/v3/scan/api/v1/images/1b28bd68-503b-4551-9151-c2d6969394d6/de81fbb7-f6c0-4e02-a305-3ce1a9c316bd"
}
],
"found_image_parts": [
{
"image_url": "https://test.zignsec.com/v3/scan/api/v1/images/1b28bd68-503b-4551-9151-c2d6969394d6/9cf226a4-9e4e-4500-9093-d9a74b98470d",
"name": "Signature",
"type": 204
},
{
"image_url": "https://test.zignsec.com/v3/scan/api/v1/images/1b28bd68-503b-4551-9151-c2d6969394d6/68a7245b-7b3f-4166-a289-501998ed5e21",
"name": "Portrait",
"type": 201
},
{
"image_url": "https://test.zignsec.com/v3/scan/api/v1/images/1b28bd68-503b-4551-9151-c2d6969394d6/bdac1edd-4869-41a7-ac9d-6f3217a7a713",
"name": null,
"type": 0
}
],
"found_text_fields": [
{
"barcode": null,
"field_name": "Given_Names_local",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "ERIKA"
},
{
"barcode": null,
"field_name": "Surname_local",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 2,
"VisualBarcode": 0
},
"visual": "MUSTERMANN"
},
{
"barcode": null,
"field_name": "Surname_And_Given_Names_local",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 2,
"VisualBarcode": 0
},
"visual": "MUSTERMANN ERIKA"
},
{
"barcode": null,
"field_name": "Given_Names",
"mrz": "ERIKA",
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 3,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "ERIKA"
},
{
"barcode": null,
"field_name": "Surname",
"mrz": "MUSTERMANN",
"verification_scores": {
"Barcode": 0,
"Mrz": 2,
"MrzBarcode": 0,
"MrzVisual": 3,
"Visual": 2,
"VisualBarcode": 0
},
"visual": "MUSTERMANN"
},
{
"barcode": null,
"field_name": "Surname_And_Given_Names",
"mrz": "MUSTERMANN ERIKA",
"verification_scores": {
"Barcode": 0,
"Mrz": 2,
"MrzBarcode": 0,
"MrzVisual": 3,
"Visual": 2,
"VisualBarcode": 0
},
"visual": "MUSTERMANN ERIKA"
},
{
"barcode": null,
"field_name": "Issuing_State_Name",
"mrz": "Germany",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": null
},
{
"barcode": null,
"field_name": "Issuing_State_Code",
"mrz": "D",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": null
},
{
"barcode": null,
"field_name": "Age",
"mrz": "58",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 3,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "58"
},
{
"barcode": null,
"field_name": "Document_Number",
"mrz": "T015Z7NGF",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 3,
"Visual": 2,
"VisualBarcode": 0
},
"visual": "T015Z7NGF"
},
{
"barcode": null,
"field_name": "RemainderTerm",
"mrz": "55",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 3,
"Visual": 1,
"VisualBarcode": 0
},
"visual": "55"
},
{
"barcode": null,
"field_name": " (522)",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "52"
},
{
"barcode": null,
"field_name": " (523)",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "5"
},
{
"barcode": null,
"field_name": "Address_City_local",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "KÖLN"
},
{
"barcode": null,
"field_name": "Address_local",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "51147 KÖLN^HEIDESTRASSE 17"
},
{
"barcode": null,
"field_name": "Address_Postal_Code_local",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "51147"
},
{
"barcode": null,
"field_name": "Address_Street_local",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "HEIDESTRASSE 17"
},
{
"barcode": null,
"field_name": "Authority_local",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "STADT KÖLN"
},
{
"barcode": null,
"field_name": "Card_Access_Number",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "217145"
},
{
"barcode": null,
"field_name": "Date_of_Birth",
"mrz": "1964-08-12",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 3,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "1964-08-12"
},
{
"barcode": null,
"field_name": "Date_of_Birth_CheckDigit",
"mrz": "5",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": null
},
{
"barcode": null,
"field_name": "Date_of_Expiry",
"mrz": "2027-04-05",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 3,
"Visual": 1,
"VisualBarcode": 0
},
"visual": "2027-04-05"
},
{
"barcode": null,
"field_name": "Date_of_Expiry_CheckDigit",
"mrz": "8",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": null
},
{
"barcode": null,
"field_name": "Date_of_Issue",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "2017-04-06"
},
{
"barcode": null,
"field_name": "Document_Class_Code",
"mrz": "ID",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": null
},
{
"barcode": null,
"field_name": "Document_Number_CheckDigit",
"mrz": "5",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": null
},
{
"barcode": null,
"field_name": "Eyes_Color_local",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "CRÜN"
},
{
"barcode": null,
"field_name": "FinalCheckDigit",
"mrz": "4",
"verification_scores": {
"Barcode": 0,
"Mrz": 1,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": null
},
{
"barcode": null,
"field_name": "Height",
"mrz": null,
"verification_scores": {
"Barcode": 0,
"Mrz": 0,
"MrzBarcode": 0,
"MrzVisual": 0,
"Visual": 0,
"VisualBarcode": 0
},
"visual": "160 cm"
},
{
"barcode": null,
"field_name": "MRZ_Strings",
"mrz": "IDD<",
"result_image_url": "https://test.zignsec.com/v3/scan/api/v1/images/1b28bd68-503b-4551-9151-c2d6969394d6/2e9f09cf-06b9-4f6e-a7da-ae9bacf29fe2",
"source_file_name": "img-1.jpg",
"source_image_url": "https://test.zignsec.com/v3/scan/api/v1/images/1b28bd68-503b-4551-9151-c2d6969394d6/cbc749d2-0c55-4129-a398-6a7f5589eb64"
},
{
"result_file_name": "",
"result_image_url": "https://test.zignsec.com/v3/scan/api/v1/images/1b28bd68-503b-4551-9151-c2d6969394d6/db8e29d0-1d26-47b9-8b7a-4a8384acd80d",
"source_file_name": "vid-3.mov",
"source_image_url": "https://test.zignsec.com/v3/scan/api/v1/images/1b28bd68-503b-4551-9151-c2d6969394d6/9888b13c-dfc0-4713-b711-e27935a80f5a"
}
],
"max_confidence": 0.98343426,
"min_confidence": 0.98343426,
"process_state": "Finished",
"resolution": "SUCCESS",
"resolution_message": "Percent of similarity 98.34%",
"resolution_status": "SUCCESS"
},
"selfie_analysis_process_state": "Finished",
"selfie_analysis_result": "ACCEPTED",
"selfie_max_confidence": 0,
"selfie_min_confidence": 0,
"session_status": "ACCEPTED",
"started_at": "2022-08-16T12:25:27.6800798Z",
"total_process_state": "Finished"
}
],
"analysis_summary": {
"analysis_duration_sec": 74.4,
"expert_summary": {
"error": null,
"result": "NOT_REQUESTED",
"result_title": "Not Requested"
},
"fraud_summary": {
"all_errors": [],
"error": null,
"result": "NOT_REQUESTED",
"result_reason": null,
"result_title": "Not Requested",
"risk_score": "Undefined"
},
"id_document_summary": {
"age": 58,
"document_type_name": "Germany - Id Card (2010)",
"error": null,
"expiration_date": "2027-04-05T00:00:00+00:00",
"fields": {
" (522)": "52",
" (523)": "5",
"Address_City_local": "KÖLN",
"Address_Postal_Code_local": "51147",
"Address_Street_local": "HEIDESTRASSE 17",
"Address_local": "51147 KÖLN^HEIDESTRASSE 17",
"Age": "58",
"Authority_local": "STADT KÖLN",
"Card_Access_Number": "217145",
"Date_of_Birth": "1964-08-12",
"Date_of_Expiry": "2027-04-05",
"Date_of_Issue": "2017-04-06",
"Document_Class_Code_MRZ": "ID",
"Document_Number": "T015Z7NGF",
"Eyes_Color_local": "CRÜN",
"Given_Names": "ERIKA",
"Given_Names_local": "ERIKA",
"Height": "160 cm",
"Issuing_State_Code_MRZ": "D",
"Issuing_State_Name_MRZ": "Germany",
"MRZ_Strings_MRZ": "IDD< 3.1.1 : Response Paramters Description
total_result | an overall analysis result. See Result below in 3.1.2 |
session_id | a session identifier |
start_date | session start date |
finish_date | session finish date |
provider_folder_id | an id used on the scanning at service provider side |
request_parameters | see details below in 3.1.3 |
synopsis_human_readable | human readable synopsis |
identity | identity (local values) |
identity_english | identity (English values) |
analysis_summary | see details below in 3.1.4 |
analysis_details | see details below in 3.1.5 |
documents | analyzed documents |
error | error string |
3.1.2 :Total Result( an overall analysis result)
Created | Session is created |
Analysing | Session analysis is in progress. |
Not started | Session analysis not started. |
Accepted | Session is successful.. |
Declined | Document is declined . when data is incorrect or bad document image quality. |
Failed | Session is failed . Document Image not found becuase of bad image quality or network issues . |
Not Requested | Analysis not requested . Ex: Selfie/liveness not requested |
Cancelled | Session cancelled by user |
3.1.3 : Session Parameters
relay_state | state sent from the client persisted in session. Is sent back to redirect urls and webhooks as is |
session_type | session type Api | BrowserFlow | WebSdk |
webhook | webhook url |
target | to be used by the Browser Flow to redirect user when analysis is finished |
target_error | to be used by Browser Flow to redirect user when analysis is FAILED |
analysis_types | an array of the Document | Selfie |(Fraud and Expert are not available, have been deprecated) |
| Field | Description |
|---|
3.1.4 :Analysis Summary Model
session_id | a session identifier |
total_process_state | The total process state for all analyses. Indicated whether the analyses are finished or not. NotRequested : analysis not requested |
session_parameters | session parameters. |
result | an overall analysis result. See 3.1.2 |
result_title | result string representation |
result_reason | result reason string |
analysis_duration_sec | analysis duration in seconds |
id_document_summary | ID Document Summary 3.1.7 |
selfie_summary | See 3.1.6 |
fraud_analysis_summary | not available |
expert_analysis_summary | not available |
3.1.5 :Analysis results details
| Field | Description |
|---|---|
total_process_state | The total process state for all analyses. Indicated whether the analyses are finished or not. NotRequested : analysis not requested |
document_analysis_state | The state for the document analysis. |
document_analysis_result | The result for the document analysis. |
document_analysis_failed_fields | Failed fields in csv format. |
fraud_analysis_state | Not available |
fraud_analysis_result | Not available |
fraud_analysis_risk_score | Not available |
expert_analysis_state | Not available |
expert_analysis_result | Not available |
identity | If the id document analysis was performed, this is an object containing the properties pertaining to the identified person. |
document_analysis_details | Contains a collection of scanned document fields. Each text field contains the field value and optional verification scores. |
fraud_analysis_details | Not available |
expert_analysis_details | Not available |
analysed_documents | The documents that were analysed in this analysis. See 3.1.7 |
3.1.6 Selfie Summary Model
Represents a selfie analysis summary
result | an overall analysis result. See 3.1.2 |
result_title | result string representation |
result_reason | reason behind the result (usually – for DECLINED sessions) |
error | all errors as a text |
min_confidence | min confidence in the selfie match |
max_confidence | max confidence in the selfie match |
3.1.7 Id Document Summary Model
Represents an id document analysis summary
result | an overall analysis result. See 3.1.2 |
result_title | result string representation |
result_reason | reason behind the result (usually – for DECLINED sessions) |
error | all errors as a text |
document_type_name | a document type name of the first found document |
first_name | first name (local value) |
last_name | last name (local value) |
full_name | full name (local value) |
first_name_english | first name (English) |
last_name_english | last name (English) |
full_name_english | full name (English) |
age | age |
expiration_date | document expiration date |
issuer_state | document issuer state |
fields | found fields formatted as a JSON object |
