Skip to content
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:
To acquire a session_token the company server has to call the 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:
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:
| |
The company server now has to check for a result. This is done by calling the 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.
Want to print your doc?
This is not the way.
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.