Documentation

Explore

Identomat System Manual & Integration Guide

Developer Guide

Introduction

Identomat is a service for checking human identity and liveness over the Internet. The manual assumes the integrating company (later "the company") has a web server (later "the company server") running at example.com and has a company_key. The company_key is a password for communicating from the company server to the Identomat server (widget.identomat.com). As an option for additional security, companies can use HMAC Authorization. The secret_key is the encryption key used with HMAC.

Procedure

The procedure is simple and consists of the following steps:

Acquiring a session_token,

Redirecting the user's browser to widget.identomat.com, and

Checking for a result.

To acquire a session_token the company server has to call the

begin/⁠

page and pass the following arguments: company_key and flags. Company server can also provide a custom steps object as an argument. The page like other pages can be called using HTTP GET or POST method. The parameters can be passed in a query string or as a URL-encoded form data or as a request body containing a JSON document. The flags parameter is an object containing the details about the identification process. Currently it may have the following format:

{

// Where to return after the identification.

// Omitting this means you are embedding in an iframe.

"return_url": <String>,

// Whether or not to check liveness of the user. Default: false

"liveness": <Boolean>,

// User interface language. Possible values: "en", "es", "ru", "uk", "gr", etc. Default: "en"

"language": <String>,

// A list of allowed documents.

// Possible item values: "id", "passport", "driver_license",

// "residence_license". Default: everything

"document_types": <Array>,

// Limit document scanning by country codes.

// Possible item values: "USA", "DEU", "ITA", etc.

"document_countries": <Array>,

// A list of allowed general documents.

// Works only if allow_general_document_capture or allow_general_document_upload is set.

// Possible item values: "bank_statement", "utility_bill", "drivers_license"

"general_document_types": <Array>,

// Allow capture of general document.

// Default: false,

"allow_general_document_capture": <Boolean>,

// Allow upload of general document.

// Default: false,

"allow_general_document_upload": <Boolean>,

// Skip agreement step completely

// Default: false

"skip_agreement": <Boolean>,

// Skip document scanning step completely

// Default: false

"skip_document": <Boolean>,

// Skip face scanning step completely

// Default: false

"skip_face": <Boolean>,

// Allow upload of an image as a document

// Default: false

"allow_document_upload": <Boolean>,

// Allow person to upload a selfie

// Default: false

"allow_face_upload": <Boolean>,

// Allow a person to upload an image of them holding a document in hand

// Default: false

"allow_face_doc_upload": <Boolean>,

// Require a person to hold a document in a hand

// Default: false

"require_face_document": <Boolean>,

// Disable document capture with camera

// Default: false

"disable_document_capture": <Boolean>,

// Skip personal computer, mac browser session and display QR code to continue on mobile device

// Default: false

"skip_desktop": <Boolean>,

// Instead of capturing passport's single page, capture double

// Default: false

"capture_double_page_passport": <Boolean>,

// Enable email verification step

// Default: false

"require_email_check": <Boolean>,

// Enable email collection step

// Default: false

"require_email": <Boolean>,

// Enable phone number verification step

// Default: false

"require_phone_number_check": <Boolean>,

// Enable phone number collection step

// Default: false

"require_phone_number": <Boolean>,

// Provide custom url in qr code when camera is not present or access is restricted

"switch_device_url": <String>

// Restrict sharing of the session URL to continue from another browser.

// Note: If this flag is true, when camera permission is denied or camera is inaccessible

// the QR code will not appear unless switch_device_url flag is present.

// Default: false

"restrict_url_sharing": <Boolean>,

// Enable device switch tab

// Default: false

"optional_continue_on_another_device": <Boolean>,

// Allows video call sessions to receive multiple participants instead of one.

// Default: false

"multiple_participants": <Boolean>,

// Enable Cascading identity verification for SDKs.

// Default: false

"cascading_identity_verification": <Boolean>

}

Steps object provides the description of the flow of the identification process. Steps array is passed along with the company_key and flags.

{

"steps": [{

// The type of the step may be either operator-questionnaire or client-questionnaire

"type": <Enum>,

"key": <String>,

"step_specific_var_1": <String, Object>,

"step_specific_var_2": <String, Object>,

...

"step_specific_var_n": <String, Object>,

// Step description supports Markdown formatting

}]

}

Below is a curl example with the flags containing a return URL https://example.com/ and user-questionnaire step:

curl https://widget.identomat.com/external-api/begin/ -d '{

"company_key": "0123456789012345678901234567890123456789",

"flags": {

"return_url": "https://example.com/"

} ,

"steps": [

{

"type": "user-questionnaire",

"key": "employment",

"title": "Employment stats",

"description": "დასაქმება",

"questions": [

{

"type": "boolean",

"mandatory": true,

"title": {

"en": "Are you currently employed?",

"ka": "ხართ თუ არა ამჟამად დასაქმებული?"

"key": "are-you-employed"

}

]

}

]

More detailed information on steps could be found in the link descriptions below:

⁠

operator-questionnaire⁠

- Operator questionnaire step

⁠

user-questionnaire⁠

- User questionnaire step

The response from all the methods is always a JSON document. This method returns a unique session_token.

Depending on the platform used for integration, follow the applicable documentation:

Web⁠

Android⁠

iOS⁠

⁠

The company server now has to check for a result. This is done by calling the

result/⁠

page and passing the company_key and the session_token parameters. It returns a JSON document containing all the information about the user. The document has the following format:

{

// The result of the identification process.

// Possible values:

// * "APPROVED" - The person was acceptable.

// * "REJECTED" - The person was unacceptable.

// * "MANUAL_CHECK" - A person was suspiciously acceptable. Human review required.

// * "IN_PROGRESS" - The person is undergoing check or has quit the process before completion.

"result": <String>,

// Whether or not the person was considered as live

"live": <Boolean>,

// A number between 0 to 1 of how much

// the person photo matched the one in the document.

// The more the value the more the match.

"similarity": <Number>,

// The document with which the process was fulfilled.

"document_type": <String>,

// List of general documents with which the process was fulfilled.

// Extracted data from proof of address documents will appear here.

"generalDocuments": [{

"documentType": <String>,

"pages": <Array>

}],

// An object describing why the session was rejected.

// Can be null.

"reject_reason": {

// The rejection reason code.

"value": <String>,

// A human-readable explanation.

"description": <String>

// The structured data extracted from a person document.

// Every member is optional.

"person": {

"local_first_name": <String>,

"local_last_name": <String>,

"first_name": <String>,

"last_name": <String>,

"birthday": <String>,

"birthday_time": <String>,

"age": <Number>,

"birth_place": <String>,

"citizenship": <String>,

"nationality": <String>,

"document_number": <String>,

"document_issued": <String>,

"document_expires": <String>,

"document_expires_time": <String>,

"personal_number": <String>,

"authority": <String>,

"issuing_state": <String>,

"sex": <String>,

"address": <String>,

"email": <String>,

"phone": <String>,

"status": <String>,

"mrz": <String>

// Session configuration ID

"configId": <String>,

// Trusted database record.

"trustedDatabaseRecord": <Object>,

// If Operator Rejects/Approves the session manually and adds a comment, that comment will be provided here

"result_comment": <String>,

// In case of the session having the questionnaire this object will return array containing answers

Gallery

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.