Developer guide

The Developer Guide provides comprehensive instructions and best practices for integrating with our platform.

Last updated 9 days ago

Was this helpful?

is a service designed for verifying human identity and liveness over the Internet. This manual assumes that the integrating company (hereafter referred to as "the company") operates a web server (hereafter referred to as "the company server") at example.com and has a company_key. The company_key is a credential used for secure communication between the company server and the Identomat server (widget.identomat.com).

For enhanced security, companies have the option to implement HMAC authorization. The secret_key serves as the encryption key used with HMAC.

Procedure

The procedure is straightforward and consists of the following steps:

Acquiring a session token

To acquire a session_token, the company server needs to call the begin/ endpoint and provide the following arguments: company_key, flags and steps (Please note that the session token has a default validity period of 15 minutes.) The steps array contains the configuration for individual steps in the identification process, each of which can have its own set of flags specific to that step.

The endpoint used to create a session_token: https://widget.identomat.com/begin/ For more details check This endpoint, like others, can be accessed using the HTTP POST method. The parameters can be passed in the query string, as URL-encoded form data, or as a request body containing a JSON document.

The flags parameter is an object that specifies the overall details of the identification process. The steps array allows for customization of each step, including step-specific flags, providing flexibility in configuring the process.

To ensure compatibility between the old and new methods, both of which need to work together, you should use the 'skip_face' and 'skip_document' flags when using steps.

These flags prevent the 'identity-document' and 'liveness' steps from being duplicated if they already exist in the flow.

To start a verification session, the company server must redirect the user’s browser to:

https://widget.identomat.com/?session_token={session_token_here}

Embedding in an Iframe

Alternatively, the widget can be embedded within an iframe:

<iframe
    src="https://widget.identomat.com/?session_token={session_token_here}"
    allow="camera">
</iframe>

Checking for a result

Once the identification process is completed:

If redirected, the user’s browser is sent back to the return URL specified in the configuration. A session_token parameter is appended to this URL.
If embedded in an iframe, the process completion can be detected using JavaScript:

addEventListener('message', function (e) {
    if (e.origin !== 'https://widget.identomat.com') return;
    if (e.data !== 'DONE') return;
    // Process completed, handle results here
});

Flags

Below is a list of all the general flags currently used by the system.

Flag name

Description

Default

Type

"skip_face"

Prevents the 'liveness' from being duplicated if it already exists in the flow as a step.

false

'skip_document'

Prevents the 'identity-document' from being duplicated if it already exists in the flow as a step.

false

"return_url"

The URL to redirect the user to after the identification process is complete.

If omitted, it indicates that the process is embedded in an iframe.

"language"

The language for the user interface.

Possible values:

"es", "ka", "uk", "ru", "uz", "it", "gr", "tr", "ro", "ar", "de", "pl", "hi", "bn", "az", "ja", "pt", "fr", "kk", "sv"

"en"

"skip_desktop"

Limits sessions to mobile devices. If the session is initiated on a desktop, a QR code will be displayed to transfer the session to a mobile device.

Possible values:

true, false

false

"switch_device_url"

Specifies a custom URL to display in the QR code when the camera is not available or access is restricted.

If omitted or set to an empty string, no URL is applied.

"restrict_url_sharing"

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

Note: If this flag is set to true, the QR code will not appear when camera access is denied or unavailable, unless the switch_device_url flag is also present.

Possible values:

true, false

false

"optional_continue_on_another_device"

Enables the option to switch to another device for continuation.

Possible values:

true, false

false

Steps

The steps array defines the flow of the identification process. The steps array is passed along with the company_key and flags.

Each step in the steps array may include the following properties.

Type: A type of the specific step.
Key: A unique identifier for the step. Keys are editable and can be configured as desired, provided they remain unique.
Flags: Specific flags that define the step's configuration.
Title: The title for the step is provided by client, displayed in the user interface.

Below is a list of all the types of steps available in our system.

Language

The Language step allows the user to choose the interface language.

Language step configurations:

Title: Language
Type: language
Key: language
Array of languages

Flag

Description

Default

Type

"languages"

Possible values:

"en", "ka", "es", "uk", "gr", "it", "de", "ru", "uz", "ro", "tr", "ar", "pl", "bn", "hi", "hy", "az", "ja", "pt", "fr", "kk", "sv"

If the array is empty, all available languages will be shown.

<array>

Expand to view example

curl https://widget.identomat.com/external-api/begin/ -d '{
    "company_key": "your_company_key_here",
    "flags": {
        "return_url": "https://example.com/",
        "language": "es"
    } ,
    "steps": [
     {
                "title": {
                  "en": "Language",
                  "ka": "ენა",
                  "es": "Idioma",
                  "uk": "Мова",
                  "gr": "Γλώσσα",
                  "it": "Lingua",
                  "de": "Sprache",
                  "ru": "Язык",
                  "uz": "Til",
                  "ro": "Limbă",
                  "tr": "Dil",
                  "ar": "اللغة",
                  "pl": "Język",
                  "bn": "ভাষা",
                  "hi": "भाषा",
                  "hy": "Լեզու",
                  "az": "Dil",
                  "ja": "言語",
                  "pt": "Idioma",
                  "fr": "Langue",
                  "kk": "Тіл",
                  "sv": "Språk"
                },
                "type": "language",
                "key": "language",
                "languages": [
                    "en",
                    "ka",
                    "es",
                    "uk",
                    "gr",
                    "it",
                    "de",
                    "ru",
                    "uz",
                    "ro",
                    "tr",
                    "ar",
                    "pl",
                    "bn",
                    "hi",
                    "hy",
                    "az",
                    "ja",
                    "pt",
                    "fr",
                    "kk",
                    "sv"
                ]
            },
            {
                "title": {
                  "en": "ID verification",
                  "ka": "პირადობის დადასტურება",
                  "es": "Verificación de identidad",
                  "uk": "Підтвердження особи",
                  "gr": "Επαλήθευση ταυτότητας",
                  "it": "Verifica dell'identità",
                  "de": "Identitätsprüfung",
                  "ru": "Проверка удостоверения личности",
                  "uz": "Shaxsni tasdiqlash",
                  "ro": "Verificare a identității",
                  "tr": "Kimlik doğrulama",
                  "ar": "التحقق من الهوية",
                  "pl": "Weryfikacja tożsamości",
                  "bn": "পরিচয় যাচাই",
                  "hi": "पहचान सत्यापन",
                  "hy": "Անձնագրի հաստատում",
                  "az": "Şəxsiyyətin təsdiqi",
                  "ja": "本人確認",
                  "pt": "Verificação de identidade",
                  "fr": "Vérification d'identité",
                  "kk": "Жеке басын тексеру",
                  "sv": "ID-verifiering"
            },
                "type": "identity-document",
                "key": "select_document_id-1",
                "flags": {
                    "document_types": [
                        "id",
                        "passport",
                        "driver_license",
                        "residence_license"
                    ],
                    "allow_document_upload": false,
                    "disable_document_capture": false
                }
            }
    ]
}'

Identity document verification

The Identity Document step involves users scanning or uploading photos of their ID documents.

Identity document step configurations:

Title: ID verification
Type: identity-document
Key: identity-document
Flags:
- disable_document_capture
- allow_document_upload
- document_types
- document_countries

Flag

Description

Default

Type

"disable_document_capture"

If true, users are unable to scan documents and must upload them instead.

Possible values:

true, false

false

"allow_document_upload"

If true, users can choose between scanning or uploading their documents.

Possible values:

true, false

false

"document_types"

A list of allowed document types.

Possible values:

"id", "passport", "driver_license", "residence_license"

If omitted or set to an empty array, all document types are allowed.

<array>

"document_countries"

Limits document scanning to specific issuer countries by codes. Possible values:

"USA", "DEU", "ITA", etc.

If omitted or set to an empty array, no restrictions are applied.

<array>

cURL example:

Example using cURL with return_url & language flags and an identity-document verification step:

Expand to view example

curl https://widget.identomat.com/external-api/begin/ -d '{
    "company_key": "your_company_key_here",
    "flags": {
        "return_url": "https://example.com/",
        "language": "es"
    } ,
    "steps": [
     {
            "title": {
                "es": "ID verification"
                ,
            "type": "identity-document",
            "key": "select_document_id",
            "flags": {
                "allow_document_upload": true,
                "document_types": [
                    "id",
                    "passport",
                    "driver_license",
                    "residence_license"
                ]
            }
        }
    ]
}'

Liveness check

In the liveness check step, the user positions their face within the frame and follows the instructions.

Identomat offers two types of liveness check:

Passive liveness: A basic check where the user holds their head within an oval frame while the system captures a two-second video.
Active liveness: An advanced biometric check where the user performs specific actions to confirm their presence as a live person.

Liveness check step configurations:

Title: Liveness
Type: liveness
Key: liveness
Flags:
- liveness
- allow_face_upload

Flag

Description

Default

Type

"liveness"

If true, users will be required to perform active liveness checks. If false, users will undergo passive liveness checks.

Possible values:

true, false

false

"allow_face_upload"

If true, users are allowed to upload a selfie. Note: If the "liveness" flag is set to true, the "allow_face_upload" flag will not be effective, as active liveness requires users to follow specific instructions.

false

cURL example:

Example using cURL with document_countries & language flags and identity-document verification & active liveness steps:

Expand to view example

curl https://widget.identomat.com/external-api/begin/ -d '{
    "company_key": "your_company_key_here",
    "flags": {
        "language": "en"
    },
    "steps": [
        {
            "title": {
                "en": "ID verification"
                },
            "type": "identity-document",
            "key": "select_document_id",
            "flags": {
                "allow_document_upload": true,
                "document_types": [
                    "id",
                    "passport",
                    "driver_license",
                    "residence_license"
                ],
                "document_countries": [
                    "USA",
                    "FRA"
                ]
            }
        },
        {
            "title": {
                "en": "Liveness check"
                },
            "type": "liveness",
            "key": "liveness",
            "flags": {
                "liveness": true
            }
        }
    ]
}'

Proof of address

The proof of address step includes verification of proof of address and analysis of other type of documents.

Proof of address step configurations:

Title: Proof of address
Type: general-document
Key: select_general_document
Flags:
- general_document_types

Flag

Description

Default

Type

"general_document_types"

A list of allowed document types.

Possible values:

"bank_statement", "utility_bill", "yellow_slip", "drivers_license", "vehicle_registration_certificate"

If omitted or set to an empty array, all general document types are allowed.

<array>

cURL example:

Example using cURL with optional_continue_on_another_device & language flags and liveness & general-document steps:

Expand to view example

curl https://widget.identomat.com/external-api/begin/ -d '{
"company_key": "your_company_key_here",
"flags": {
        "optional_continue_on_another_device": true,
        "language": "en"
},
"steps": [
    {
        "title": {
            "en": "Liveness check"
            },
        "type": "liveness",
        "key": "liveness",
        "flags": {
            "liveness": true
        }
    },
    {
        "title": {
            "en": "General documents"
            },
        "type": "general-document",
        "key": "select_general_document",
        "flags": {
            "general_document_types": [
                "bank_statement",
                "utility_bill",
                "yellow_slip",
                "drivers_license",
                "vehicle_registration_certificate"
            ]
        }
    }
]
}'

Selfie with ID

In the Selfie with ID step, users are required to hold their document in their hands so that both their face and the document are visible.

Selfie with ID step configurations:

Title: Selfie with ID
Type: face-document
Key: capture_face_document
Flags:
- allow_face_doc_upload
- require_face_document

Flag

Description

Default

Type

"allow_face_doc_upload"

If true, users are allowed to upload an image of themselves holding a document in their hand.

Possible values:

true, false

false

"require_face_document"

If true, users are allowed to capture themselves holding a document in their hand.

Possible values:

true, false

false

cURL example:

Example using cURL with restrict_url_sharing & language flags and face-document step:

Expand to view example

curl https://widget.identomat.com/external-api/begin/ -d '{
"company_key": "your_company_key_here",
"flags": {
        "restrict_url_sharing": true,
        "language": "it"
},
"steps": [
    {
        "title": {
            "it": "Face document"
            },
        "type": "face-document",
        "key": "capture_face_document",
        "flags": {
            "allow_face_doc_upload": true,
            "require_face_document": true
        }
    }
]
}'

Video call

In the Video Call step, the user is connected with an operator to perform a manual verification process. The video call may include all other Identomat verification steps.

Identomat offers two types of video call:

One-on-one: Involves a secure video call between a customer and a verification operator
Multi-user call: Enables the verification of multiple customers within a single session. Each user can follow their own customized workflow tailored to the specific business process.

Video call step configurations:

Title: Video call
Type: video-call
Key: video-call
Array of steps
resetSteps: true/false (optional)
hideCameraOption: true/false (optional)
nameRequired: true/false (optional)
multiple_participans: true/false (optional)

Flag

Description

Default

Type

"steps"

The steps array includes all identification steps listed here, except for the language step and the operator_questionnaire, which must be listed outside the video call steps array.

empty array [ ]

<array>

"resetSteps"

If a user disconnects and rejoins the call, all previous verification data is cleared for security reasons. The operator must restart the verification process to ensure the user's identity.

Possible values:

true, false

false

"hideCameraOption"

Enabling this will hide the camera icon, preventing users from turning off the camera. Possible values:

true, false

false

"nameRequired"

If enabled, participants are required to provide their names to join the call. Possible values:

true, false

false

"multiple_participants"

true, allows video call sessions to include multiple participants instead of just one.

Possible values:

true, false

false

cURL example:

Example using cURL with return_url & language flags and video-call with identity-document step:

Expand to view example

curl https://widget.identomat.com/external-api/begin/ -d '{
"company_key": "your_company_key_here",
"flags": {
        "return_url": "https://example.com/",
        "language": "es"
},
"steps": [
    {
            "type": {
                "es": "video-call"
                },
            "key": "video-call",
            "steps": [
                {
                    "title": {
                        "es": "ID verification"
                        },
                    "type": "identity-document",
                    "key": "select_document_id",
                    "flags": {
                        "document_types": [
                            "id",
                            "passport",
                            "driver_license",
                            "residence_license"
                        ]
                    }
                }
            ]
        }
]
}'

Phone number

Phone number verification allows users to verify their phone number using an OTP code.

Phone number step may include:

Verification of the user's phone number using an OTP code.
Collection of the user's phone number.

Phone number step configurations:

Type: phone-number
Key: phone_number
Flags:
- require_phone_number_check
- require_phone_number

Flag

Description

Default

Type

"require_phone_number_check"

If true, users are required to verify their phone number using an OTP code sent to them.

Possible values:

true, false

false

"require_phone_number"

If true, users are required to submit their phone number without verification.

Possible values:

true, false

false

cURL example:

Example using cURL with return_url & language flags and phone-number step:

Expand to view example

curl https://widget.identomat.com/external-api/begin/ -d '{
"company_key": "your_company_key_here",
"flags": {
        "return_url": "https://example.com/",
        "language": "it"
},
"steps": [
    {
        "title": {
            "it": "Phone number verification"
            },
        "type": "phone-number",
        "key": "phone_number",
        "flags": {
            "require_phone_number_check": true
        }
    }
]
}'

Email

Email step allows users to verify their email using an OTP code.

Email step may include:

Verification of the user's email using an OTP code.
Collection of the user's email.

Email step configurations:

Type: email
Key: require_email
Flags:
- require_email_check
- require_email

Flag

Description

Default

Type

"require_email_check"

If true, users are required to verify their email using an OTP code sent to them.

Possible values:

true, false

false

"require_email"

If true, users are required to submit their email address without verification.

Possible values:

true, false

false

cURL example:

Example using cURL with return_url & language flags and phone-number step:

Expand to view example

curl https://widget.identomat.com/external-api/begin/ -d '{
"company_key": "your_company_key_here",
"flags": {
        "return_url": "https://example.com/",
        "language": "en"
},
"steps": [
    {
        "title": {
            "en": "Email verification"
            },
        "type": "email",
        "key": "require_email",
        "flags": {
            "require_email_check": true
        }
    }
]
}'

Geolocation

The Geolocation step allows the user to grant permission for location access. This enables the system to retrieve the user's geolocation data, including coordinates and address.

Geolocation step configurations:

Type: geolocation
Key: require_geolocation
Flags:
- require_geolocation

Flag

Description

Default

Type

"require_geolocation"

If true, users must grant permission for location access to proceed.

Possible values:

true, false

true

cURL example:

Example using cURL with return_url & language flags and geolocation step:

Expand to view example

curl https://widget.identomat.com/external-api/begin/ -d '{
"company_key": "your_company_key_here",
"flags": {
        "return_url": "https://example.com/",
        "language": "en"
},
"steps": [
    {
        "title": {
            "en": "Geolocation"
            },
        "type": "geolocation",
        "key": "require_geolocation",
        "flags": {
            "require_geolocation": true
        }
    }
]
}'

User questionnaire

The User questionnaire step is designed for various types of forms that users are required to fill out. All information provided by the user is saved within the session. Questionnaire steps have slightly different parameters compared to other steps.

User questionnaire step configurations:

"type": user-questionnaire
"key": Keys are chosen by the client and must remain unique within a single session.
"title": The title of the user questionnaire, displayed as the block title on the user's side. The title can be an <object> containing different languages, allowing the title to be displayed in the selected language during the verification flow.
"description": A description that appears below the title on the user's side. Similar to the title, the description can be an <object> containing different languages, so that it can be displayed in the selected language during the verification flow.
"questions": An <array> of questions with the following types:
- string: Text Input - The user is required to fill out a short text form with an answer string.
- multiple-choice: Checkboxes - The user can select one or more answers from a list of options.
- options: Radio Buttons - The user can choose only one answer from a set of options.
- dropdown : A selectable menu where the user can choose a single or multiple options from a list.
- file: Allows the user to upload a file as a response.
"successButtonTitle": The title of the action button in the questionnaire. If the questions are mandatory, the button is deactivated until the user completes the questionnaire.

Questions

Questions consist of these parameters:

"type": The type of the question. There are three types: string, multiple-choice ,options, dropdown, file.
"title": The title is an <object> of languages so that if the user changes the language during the verification flow, the question can be displayed in different languages. There are no length or symbol restrictions.
"key": The key for the question, chosen by the client. It must remain unique within a single questionnaire.
"mandatory": Specifies whether the question is required to be answered.
"answer": Allows to preset an answer for a question. To preset an answer for options-type questions, the key of the desired option should be assigned as the value of the answer parameter. For string-type questions, the answer can be pre-filled by directly assigning the desired text to the value of the answer parameter. In case of multiple-choice questions, the value of the answer parameter is an array containing the keys of all the answers that should be pre-selected. Note: the end-users can modify the preset answer.
"readOnly": Displays the question to the user but restricts any interaction, meaning the user will be unable to choose, fill, or edit an answer.
"showConditions": This parameter may be used to set conditions for whether a question should be displayed. It consists of:
- "questionKey": The key of the question that serves as the condition for the current question.
- "answer": The key of the answer to the conditional question, or the specific answer text in the case of a text string.
"multiple": This parameter can be used for a dropdown-type question to allow multiple selections by the user.

Options

Options are used only for multiple-choice and options types of questions. They consist of the following parameters:

"options": An <array> of options for the question. Each option may have:
- "title" : The title of an option. The title can be an <object> containing different languages, allowing the option to be displayed in the selected language during the verification flow.
- "key": The key for the option, chosen by the client. It must remain unique within a single questionnaire.

List of parameters with examples:

Parameter

Description

Default

Type

Example

"key"

Keys are chosen by the client and must remain unique within a single session.

Recommended to use key describing the questionnaire shortly.

"key": "terms-and-conditions"

"title"

The title of the user questionnaire, displayed as the block title on the user's side. The title can be an <object> containing different languages, allowing the title to be displayed in the selected language during the verification flow.

"title": { 
"es": "Tu título",
"en": "Your title"
}

"description"

A description that appears below the title on the user's side. Similar to the title, the description can be an <object> containing different languages, so that it can be displayed in the selected language during the verification flow.

"description": {
"es": "Tu descripción",
"en": "Your description"
}

"questions"

An <array> of questions with the following types: string, multiple-choice , options, dropdown.

<array>

"questions": [
    {
    "type": "string",
    "title": { 
        "es": "Tu título",
        "en": "Your title"
        }
    "key": "question1",
    "mandatory": true
    },
    {
    "type": "multiple-choice",
    "title": { 
        "es": "Tu título",
        "en": "Your title"
        },
    "key": "question2",
    "mandatory": false,
    "options": [
        {
        "title": { 
        "es": "Tu título",
        "en": "Your title"
        },
        "key": "option1"
        },
        { 
        "title": { 
        "es": "Tu título",
        "en": "Your title"
        },
        "key": "option2"
        }
    ]
    }
]

"mandatory"

Specifies whether the question is required to be answered.

Possible values:

true, false

false

"mandatory": false

"answer"

Allows to preset an answer for a question.

"answer": "option2"

"readOnly"

Displays the question but restricts interaction.

false

"readOnly": false

"showConditions"

This parameter may be used to set conditions for whether a question should be displayed.

"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }

"successButtonTitle"

The title of the action button in the questionnaire. If the questions are mandatory, the button is deactivated until the user completes the questionnaire.

Confirm

"successButtonTitle": { 
"es": "Tu título",
"en": "Your title"
}

cURL example:

Expand to view user-questionnaire example

curl https://widget.identomat.com/external-api/begin/ -d '{
"company_key": "your_company_key_here",
"flags": {
        "restrict_url_sharing": true,
        "language": "es"
},
"steps": [
    {
            "key": "questionnaire-page-1",
            "type": "user-questionnaire",
            "title": { 
                "es": "Tu título",
                "en": "Your title"
                },
            "description": {
                "es": "Tu descripción",
                "en": "Your description"
                },
            "questions": [
                {
                "type": "string",
                "title": {
                "es": "Tu título",
                "en": "Your title"
                },
                "key": "question1",
                "mandatory": true
                },
                {
                "type": "multiple-choice",
                "title": {
                "es": "Tu título",
                "en": "Your title"
                },
                "key": "question2",
                "mandatory": false,
                "options": [
                    {
                    "title": {
                    "es": "Tu título",
                    "en": "Your title"
                    },
                    "key": "option1"
                    },
                    { 
                    "title": {
                    "es": "Tu título",
                    "en": "Your title"
                    },
                    "key": "option2"
                    }
                ],
                "answer": ["option2"],
                "readOnly": true
                },
                {
                "type": "options",
                "title": {
                "es": "Tu título",
                "en": "Your title"
                },
                "key": "question3",
                "mandatory": true,
                "options": [
                    {
                    "title": {
                    "es": "Tu título",
                    "en": "Your title"
                    },
                    "key": "option3"
                    },
                    { 
                    "title": {
                    "es": "Tu título",
                    "en": "Your title"
                    },
                    "key": "option4"
                    }
                ]
            }
        ]
    }
]
}'

Question type: Text input

Available parameters:

Parameter

Description

Default

Type

Example

"type"

"string"

"type": "string"

"key"

Keys are chosen by the client and must remain unique within a single session.

Recommended to use key describing the question shortly.

"key": "your-address"

"title"

The title is an <object> of languages so that if the user changes the language during the verification flow, the question can be displayed in different languages. There are no length or symbol restrictions.

"title": { 
"es": "Tu título",
"en": "Your title"
}

"mandatory"

Specifies whether the question is required to be answered.

Possible values:

true, false

false

"mandatory": true

"answer"

Allows to preset an answer for a question. The answer is an <object> of languages so that if the user changes the language during the verification flow, the prefilled answer can be displayed in different languages.

"answer": { 
        "en": "This is a prefilled answer",
        "es":"Esta es una respuesta prellenada."
}

"readOnly"

Displays the question but restricts interaction.

false

"readOnly": true

"showConditions"

This parameter may be used to set conditions for whether a question should be displayed.

"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }

Expand to view TEXT INPUT question example

"questions": [
    {
        "type": "string",
        "title": {
            "es": "Tu título",
            "en": "Your title"
        },
        "key": "question1",
        "mandatory": true,
        "answer": {
            "en": "This is a prefilled answer",
            "es": "Esta es una respuesta prellenada."
        },
        "showConditions": {
            "questionKey": "question1",
            "answer": "option1"
        },
        "readOnly": true
    }
]

Question type: Checkbox

Available parameters:

Parameter

Description

Default

Type

Example

"type"

"multiple-choice"

"type": "multiple-choice"

"key"

Keys are chosen by the client and must remain unique within a single session.

Recommended to use key describing the question shortly.

"key": "check-two-answers"

"title"

"title": { 
"es": "Tu título",
"en": "Your title"
}

"options"

An <array> of options for the question. Each option may have:

"title" : The title of an option. The title is an <object> containing different languages, allowing the option to be displayed in the selected language during the verification flow.
"key": The key for the option, chosen by the client. It must remain unique within a single questionnaire.

<array>

"options": [
    {
        "title": {
            "en": "Identity Document",
            "es": "Documento de identidad"
        },
        "key": "identity-document"
    },
    {
        "title": {
            "en": "Proof of Address",
            "es": "Comprobante de domicilio"
        },
        "key": "proof-of-address"
    ]

"mandatory"

Specifies whether the question is required to be answered.

Possible values:

true, false

false

"mandatory": true

"answer"

Allows to preset an answer for a question. The answer is an <array> of option keys assigned to this question.

<array>

"answer": [
    "option-1",
    "option-2"
]

"readOnly"

Displays the question but restricts interaction.

false

"readOnly": true

"showConditions"

This parameter may be used to set conditions for whether a question should be displayed.

"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }

Expand to view CHECKBOX question example

"questions": [
    {
        "type": "multiple-choice",
        "title": {
            "es": "Tu título",
            "en": "Your title"
        },
        "key": "question2",
        "options": [
            {
                "title": {
                    "en": "Identity Document",
                    "es": "Documento de identidad"
                },
                "key": "identity-document"
            },
            {
                "title": {
                    "en": "Proof of Address",
                    "es": "Comprobante de domicilio"
                },
                "key": "proof-of-address"
            ],
            "mandatory": true,
            "answer": [
                "identity-document",
                "proof-of-address"
            },
            "showConditions": {
                "questionKey": "question1",
                "answer": "option1"
            },
            "readOnly": true
        }
    ]

Question type: Radio

Available parameters:

Parameter

Description

Default

Type

Example

"type"

"options"

"type": "options"

"key"

Keys are chosen by the client and must remain unique within a single session.

Recommended to use key describing the question shortly.

"key": "choose-one-answer"

"title"

"title": { 
"es": "Tu título",
"en": "Your title"
}

"options"

An <array> of options for the question. Each option may have:

"title" : The title of an option. The title is an <object> containing different languages, allowing the option to be displayed in the selected language during the verification flow.
"key": The key for the option, chosen by the client. It must remain unique within a single questionnaire.

<array>

"options": [
    {
        "title": {
            "en": "Identity Document",
            "es": "Documento de identidad"
        },
        "key": "identity-document"
    },
    {
        "title": {
            "en": "Proof of Address",
            "es": "Comprobante de domicilio"
        },
        "key": "proof-of-address"
    ]

"mandatory"

Specifies whether the question is required to be answered.

Possible values:

true, false

false

"mandatory": true

"answer"

Allows to preset an answer for a question. The answer is an <string> of an option key assigned to this question.

"answer": "option-1"

"readOnly"

Displays the question but restricts interaction.

false

"readOnly": true

"showConditions"

This parameter may be used to set conditions for whether a question should be displayed.

"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }

Expand to view RADIO question example

"questions": [
    {
        "type": "options",
        "title": {
            "es": "Tu título",
            "en": "Your title"
        },
        "key": "question3",
        "options": [
            {
                "title": {
                    "en": "Identity Document",
                    "es": "Documento de identidad"
                },
                "key": "identity-document"
            },
            {
                "title": {
                    "en": "Proof of Address",
                    "es": "Comprobante de domicilio"
                },
                "key": "proof-of-address"
            ],
            "mandatory": true,
            "answer": "identity-document",
            "showConditions": {
                "questionKey": "question1",
                "answer": "option1"
            },
            "readOnly": true
        }
    ]

Available parameters:

Parameter

Description

Default

Type

Example

"type"

"dropdown"

"type": "dropdown"

"key"

Keys are chosen by the client and must remain unique within a single session.

Recommended to use key describing the question shortly.

"key": "choose-from-list"

"title"

"title": { 
"es": "Tu título",
"en": "Your title"
}

"options"

An <array> of options for the question. Each option may have:

"title" : The title of an option. The title is an <object> containing different languages, allowing the option to be displayed in the selected language during the verification flow.
"key": The key for the option, chosen by the client. It must remain unique within a single questionnaire.

<array>

"options": [
    {
        "title": {
            "en": "Identity Document",
            "es": "Documento de identidad"
        },
        "key": "identity-document"
    },
    {
        "title": {
            "en": "Proof of Address",
            "es": "Comprobante de domicilio"
        },
        "key": "proof-of-address"
    ]

"mandatory"

Specifies whether the question is required to be answered.

Possible values:

true, false

false

"mandatory": true

"multiple"

Specifies whether the question is single or multiple choice.

Possible values:

true, false

false

"multiple": true

"showConditions"

This parameter may be used to set conditions for whether a question should be displayed.

"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }

Expand to view DROPDOWN question example

"questions": [
    {
        "type": "options",
        "title": {
            "es": "Tu título",
            "en": "Your title"
        },
        "key": "question4",
        "options": [
            {
                "title": {
                    "en": "Identity Document",
                    "es": "Documento de identidad"
                },
                "key": "identity-document"
            },
            {
                "title": {
                    "en": "Proof of Address",
                    "es": "Comprobante de domicilio"
                },
                "key": "proof-of-address"
            ],
            "mandatory": true,
            "multiple": true,
            "showConditions": {
                "questionKey": "question1",
                "answer": "option1"
            }
        }
    ]

Question type: File upload

Available parameters:

Parameter

Description

Default

Type

Example

"type"

"file"

"type": "file"

"key"

Keys are chosen by the client and must remain unique within a single session.

Recommended to use key describing the question shortly.

"key": "choose-from-list"

"title"

"title": { 
"es": "Tu título",
"en": "Your title"
}

"description"

A description that appears below the title. Similar to the title, the description can be an <object> containing different languages, so that it can be displayed in the selected language during the verification flow.

"description": {
"es": "Tu descripción",
"en": "Your description"
}

"mandatory"

Specifies whether the question is required to be answered.

Possible values:

true, false

false

"mandatory": true

"fileTypes"

Specifies the types of files the user is allowed to upload. Possible values: pdf, image.

[ "pdf", "image" ]

<array>

"fileTypes": [
    "pdf",
    "image"
]

"filesMaxCount"

Specifies the maximum number of files the user is allowed to upload. Possible values: A number from 1 to 10.

"filesMaxCount": 5

"showConditions"

This parameter may be used to set conditions for whether a question should be displayed.

"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }

Expand to view FILE UPLOAD question example

"questions": [
    {
        "type": "file",
        "title": {
            "es": "Tu título",
            "en": "Your title"
        },
        "key": "question5",
            "mandatory": true,
            "fileTypes": [
            "pdf",
            "image"
            ],
            "filesMaxCount": 5,
            "showConditions": {
                "questionKey": "question1",
                "answer": "option1"
            }
        }
    ]

Operator questionnaire

The Operator Questionnaire is part of the session, allowing the operator to fill out various forms to collect information from the user or to input session details. The configurations of the Operator Questionnaire are very similar to those of the User Questionnaire.

Operator questionnaire step configurations:

"type": operator-questionnaire
"key": Keys are chosen by the client and must remain unique within a single session.
"title": The title of the operator questionnaire, displayed as the tab name in the session. The title can be an <object> containing different languages, allowing the title to be displayed in the selected language.
"description": Similar to the title, the description can be an <object> containing different languages, so that it can be displayed in the selected language.
"questions": An <array> of questions with the following types:
- string: Text Input - The operator is required to fill out a short text form with an answer string.
- multiple-choice: Checkboxes - The operator can select one or more answers from a list of options.
- options: Radio Buttons - The operator can choose only one answer from a set of options.

Questions

Questions consist of these parameters:

"type": The type of the question. There are three types: string, multiple-choice and options.
"title": The question title as a string. There are no length or symbol restrictions. The title can also be an <object> of languages so that if the user changes the language during the verification flow, the question can be displayed in different languages.
"key": The key for the question, chosen by the client. It must remain unique within a single questionnaire.
"mandatory": Specifies whether the question is required to be answered.
"answer": Allows to preset an answer for a question. To preset an answer for options-type questions, the key of the desired option should be assigned as the value of the answer parameter. For string-type questions, the answer can be pre-filled by directly assigning the desired text to the value of the answer parameter. In case of multiple-choice questions, the value of the answer parameter is an array containing the keys of all the answers that should be pre-selected. Note: the operators can modify the preset answer.
"readOnly": Displays the question to the operator but restricts any interaction, meaning the operator will be unable to modify the answer.
"showConditions": This parameter may be used to set conditions for whether a question should be displayed. It consists of:
- "questionKey": The key of the question that serves as the condition for the current question.
- "answer": The key of the answer to the conditional question, or the specific answer text in the case of a text string.

Options

Options are used only for multiple-choice and options types of questions. They consist of the following parameters:

"options": An <array> of options for the question. Each option may have:
- "title" : The title of an option. The title can be an <object> containing different languages, allowing the option to be displayed in the selected language during the verification flow.
- "key": The key for the option, chosen by the client. It must remain unique within a single questionnaire.

List of parameters with examples:

Parameter

Description

Default

Type

Example

"key"

Keys are chosen by the client and must remain unique within a single session.

Recommended to use key describing the questionnaire shortly.

"key": "document-collection"

"title"

The title of the operator questionnaire, displayed as the tab name in the session. The title can be an <object> containing different languages, allowing the title to be displayed in the selected language.

"title": { 
"es": "Tu título",
"en": "Your title"
}

"description"

Similar to the title, the description can be an <object> containing different languages, so that it can be displayed in the selected language.

"description": {
"es": "Tu descripción",
"en": "Your description"
}

"questions"

An <array> of questions with the following types: string, multiple-choice and options.

<array>

"questions": [
    {
    "type": "string",
    "title": "Your title",
    "key": "question1",
    "mandatory": true
    },
    {
    "type": "multiple-choice",
    "title": "Your title",
    "key": "question2",
    "mandatory": false,
    "options": [
        {
        "title": "Your title",
        "key": "option1"
        },
        { 
        "title": "Your title",
        "key": "option2"
        }
    ]
    }
]

"mandatory"

Specifies whether the question is required to be answered.

Possible values:

true, false

false

"mandatory": false

"answer"

Allows to preset an answer for a question.

"answer": "option2"

"readOnly"

Displays the question but restricts interaction.

false

"readOnly": false

"showConditions"

This parameter may be used to set conditions for whether a question should be displayed.

"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }

cURL example:

Expand to view operator-questionnaire example

curl https://widget.identomat.com/external-api/begin/ -d '{
    "company_key": "your_company_key_here",
    "flags": {
        "restrict_url_sharing": true,
        "language": "es"
    },
    "steps": [
        {
            "key": "questionnaire-page-1",
            "type": "operator-questionnaire",
            "title": {
                "es": "Tu título",
                "en": "Your title"
            },
            "description": {
                "es": "Tu descripción",
                "en": "Your description"
            },
            "questions": [
                {
                    "type": "string",
                    "title": {
                        "es": "Tu título",
                        "en": "Your title"
                    },
                    "key": "question1",
                    "mandatory": true
                },
                {
                    "type": "multiple-choice",
                    "title": {
                        "es": "Tu título",
                        "en": "Your title"
                    },
                    "key": "question2",
                    "mandatory": false,
                    "options": [
                        {
                            "title": {
                                "es": "Tu título",
                                "en": "Your title"
                            },
                            "key": "option1"
                        },
                        {
                            "title": {
                                "es": "Tu título",
                                "en": "Your title"
                            },
                            "key": "option2"
                        }
                    ],
                    "answer": [
                        "option2"
                    ],
                    "readOnly": true
                },
                {
                    "type": "options",
                    "title": {
                        "es": "Tu título",
                        "en": "Your title"
                    },
                    "key": "question3",
                    "mandatory": true,
                    "options": [
                        {
                            "title": {
                                "es": "Tu título",
                                "en": "Your title"
                            },
                            "key": "option3"
                        },
                        {
                            "title": {
                                "es": "Tu título",
                                "en": "Your title"
                            },
                            "key": "option4"
                        }
                    ]
                }
            ]
        }
    ]
}'

Procedure

Acquiring a session token

Redirecting to the Identomat Widget

Embedding in an Iframe

Checking for a result

Flags

Steps

Language

Identity document verification

cURL example:

Liveness check

cURL example:

Proof of address

cURL example:

Selfie with ID

cURL example:

Video call

cURL example:

Phone number

cURL example:

Email

cURL example:

Geolocation

cURL example:

User questionnaire

Questions

Options

List of parameters with examples:

cURL example:

Question type: Text input

Question type: Checkbox

Question type: Radio

Question type: Dropdown

Question type: File upload

Operator questionnaire

Questions

Options

List of parameters with examples:

cURL example: