Skip to content
Gallery
Documentation [DRAFT]
Identomat System Manual & Integration Guide
Untitled sync page
Share
Explore
Identomat System Manual & Integration Guide

icon picker
Developer Guide

Web
Android
iOS
HMAC Authorization
API Reference

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.
// * "DISAGREED_WITH_TERMS" - The person disagreed with terms.
// * "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>
},

// 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
"questionnaires": [{
"key": <String>,
"questions": [{
"key": <String>,
"answer": <String, Boolean, Array[String]>
}]
}],

// In case of the session having screening matches this object will return array containing those matches
// You can fetch person details by calling get-screening-person-details with personId that you get in screeningMatches elements
"screeningMatches": [{
"score": <Number>,
"name": <String>,
"personId": <String>,
"reviewStatus": <String>
}],

// The structured data of technical details.
"technicalDetails": {
"remoteAddress": <String>,
"userAgent": <String>,
"countryCode": <String>

}
}
Session record can be deleted by calling
delete/
⁠
page and passing the company_key and the session_token parameters. It returns a JSON document containing all the information about the deleted session. In case of non existing session it returns SESSION_NOT_FOUND or in case of invalid session it returns SESSION_INVALID.
⁠
Previous:
Verification Checks
⁠
| Next:
Web
⁠
⁠
⁠

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.