Developer guide

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

Identomat is a service designed to verify human identity and liveness over the Internet. This guide assumes that the integrating organization (hereafter referred to as "the company") operates a web server (referred to as "the company server") at example.com and possesses a company_key. The company_key is a credential used to securely communicate between the company server and the Identomat server (widget.identomat.com).

For enhanced security, companies can optionally implement HMAC authorization. In this case, a secret_key is used as the encryption key for generating and validating HMAC signatures.

Procedure

The procedure is straightforward and consists of the following steps:

1

Acquiring a session_token.

2

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

3

Checking for a result.

Acquiring a session token

To acquire a session_token, your backend must send a request to the begin/ endpoint with the following required parameters:

• company_key – Your unique company identifier.

• flags – A JSON object that defines global settings for the verification session.

• steps – An array specifying the steps to be included in the verification flow. Each step can have its own step-specific flags.

⚠️ The session_token has a default validity period of 15 minutes.

Endpoint:

POST https://widget.identomat.com/begin/

You can send the request using one of the following formats:

• As URL query parameters

• As URL-encoded form data

• As a JSON object in the request body (recommended)

Steps and Flags Structure

• flags : Defines global behavior for the entire identification session.

• steps : Allows full control of the verification process, enabling you to specify which steps to include (e.g., liveness, identity-document) and configure step-specific flags, such as "allow_face_upload": true for the liveness step.

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.

Using Configuration or Custom Steps

You can initiate a session in two ways:

• Via predefined configuration (Recommended): Use the config_id parameter to reference a saved configuration from the dashboard.

• Via custom steps and flags: Provide a full set of steps and flags directly in the request payload.

📘 For detailed parameter definitions and examples, refer to the API Reference.

Redirecting to the Identomat Widget

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

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

Replace {session_token_here} with the actual token received from the /begin/ endpoint.

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>

⚠️ The allow="camera" attribute is required to grant camera access.

Checking for a result

Once the verification process is completed, the result can be detected in two ways depending on how the widget was integrated:

• If redirected If you used a redirect approach (not embedded in an iframe), the user will be redirected to the return_url specified in the configuration or session flags. The session_token will be appended as a query parameter:

https://yourapp.com/?session_token=abc123xyz

• 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
});

✅ Ensure you verify the message origin to avoid security risks.

---

Flags

The flags is an object with optional configuration flags that adjust the verification flow. Below is a summary of the most commonly used flags:

Flag name	Description	Default	Type
skip_face	Skips the liveness step if it already exists in the defined steps. Prevents duplication when using custom flows.	false	<boolean>
skip_document	Skips the identity-document step if it already exists in the defined steps. Prevents duplication when using custom flows.	false	<boolean>
return_url	URL to redirect the user to after the identification process is completed. If omitted, the session is assumed to be embedded in an iframe.	null	<string>
language	User interface language code. Supported values: "es", "ka", "uk", "ru", "uz", "it", "gr", "tr", "ro", "ar", "de", "pl", "hi", "bn", "az", "ja", "pt", "fr", "kk", "sv"	"en"	<string>
skip_desktop	Limits sessions to mobile devices only. If initiated on desktop, a QR code is shown to transfer the session to a mobile device.	false	<boolean>
switch_device_url	A custom URL to display in the QR code when the camera is unavailable or blocked. If omitted or empty, the QR code will not be displayed.	null	<string>
restrict_url_sharing	Prevents the session URL from being used on a different browser or device. If true, the QR code will not appear when camera access is denied—unless switch_device_url is also defined.	false	<boolean>
optional_continue_on_another_device	Allows users to optionally switch to another device to continue the session.	false	<boolean>
requireHdMedia	Enforces Full HD (1080p+) camera usage for liveness and identity-document steps. If not met, a QR code is shown for the user to switch to another device.	false	<boolean>

Steps

The steps array defines the sequence and structure of the identification process. It is included alongside the company_key and flags parameters when creating a session.

Each step in the steps array can contain the following properties:

Property	Description
type	The type of the specific step (see list of supported step types below).
key	A unique identifier for the step. This key can be customized but must remain unique within the session.
flags	Step-specific configuration flags that control the behavior of this step.
title	A custom title provided by the client, displayed to the user during this step in the interface.

Supported step types

Below is a list of all step types currently supported in the system:

• Language

• ID verification

• Liveness check

• Proof of Address

• Selfie with ID

• KYB (Know Your Business)

• Video call

• Phone number verification

• Email verification

• User questionnaire

• Operator questionnaire

Language

The Language step allows the user to select their preferred interface language at the beginning of the identification process.

Language step configurations:

• Title: Language

• Type: language

• Key: language

• Array of languages

Flag	Description	Default	Type
languages	An array of language codes to display. If left empty, all supported languages will be shown. "en", "ka", "es", "uk", "gr", "it", "de", "ru", "uz", "ro", "tr", "ar", "pl", "bn", "hi", "hy", "az", "ja", "pt", "fr", "kk", "sv"	All	Array<string>

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	Disables live document scanning. Users can only upload images of their documents.	false	<boolean>
allow_document_upload	Enables the option to either scan or upload the document.	false	<boolean>
document_types	A list of allowed document types. Possible values: "id", "passport", "driver_license", "residence_license"	All types	Array<string>
document_countries	Restricts accepted document issuers to specific country codes. (e.g., "USA", "DEU", "ITA")	Unrestricted	Array<string>

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

The Liveness step verifies that the user is physically present by analyzing a live facial image or video.

Identomat supports two types of liveness verification:

• Passive liveness: The user aligns their face within an oval frame while the system captures a short (approx. 2-second) video.

• Active liveness: 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	Defines the type of liveness check: true: active liveness false: passive liveness	false	<boolean>
allow_face_upload	Allows the user to upload a selfie instead of using the camera. ⚠️ This flag is ignored if liveness is true, as active checks require live input.	false	<boolean>

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. This step supports a wide range of general document types, such as utility bills or bank statements.

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. If omitted or set to an empty array, all document types will be available for upload. Possible values: "bank_statement", "utility_bill", "yellow_slip", "drivers_license", "vehicle_registration_certificate"	All types	<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	Allows users to upload an image of themselves holding the document.	false	<boolean>
require_face_document	Requires users to capture themselves holding the document live.	false	<boolean>

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
        }
    }
]
}'

---

KYB (Know Your Business)

The KYB flow is designed to collect and verify company data, beneficiaries, and representatives before completing the verification process.

The KYB flow consists of three steps:

1

Company data

2

Beneficiaries

3

Review

Each step is configurable with its own set of parameters.

Company data step

Collects core company information.

• Title: Company data

• Description: Follow the simple steps below

• Type: company

• Key: company

• Fields:

  • Company name (always mandatory)

  • Registration number (always mandatory)

  • Registration country (always mandatory)

  • Type of entity

  • Legal adress

  • VAT / TaxID

  • Date of Incorporation

  • Contact number

  • Contact email address

Step example:

{
  "type": "company",
  "key": "company",
  "title": { "en": "Company data" },
  "description": { "en": "Follow the simple steps below" },
  "fields": [...]
}

Step parameters:

Parameter	Description	Type
type	Step type. Must be company.	<string>
key	Unique identifier for the step.	<string>
title	Localized title text displayed as the block title to the user. The title can be an <object> containing different languages, allowing the title to be displayed in the selected language during the flow.	<object>
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 flow.	<object>
fields	List of fields to be collected during this step.	<array>

Fields:

Example:

"fields": [
                  { "type": "companyName", "mandatory": true },
                  { "type": "registrationNumber", "mandatory": true },
                  { "type": "registrationCountry", "mandatory": true },
                  { "type": "ownershipPercentage", "mandatory": false },
                  { "type": "companyEntityType", "mandatory": false },
                  { "type": "legalAddress", "mandatory": false },
                  { "type": "taxId", "mandatory": false },
                  { "type": "dateOfIncorporation", "mandatory": false },
                  { "type": "firstName", "mandatory": true },
                  { "type": "lastName", "mandatory": true },
                  { "type": "dateOfBirth", "mandatory": true },
                  { "type": "contactNumber", "mandatory": false },
                  { "type": "email", "mandatory": false }, 
                  { "type": "website", "mandatory": false }
              ]

Field	Description	Input type
companyEntityType	Mandatory field. Type of legal entity. Options include: Limited liability company Publicly listed company Sole proprietor Partnership Corporation Trust Private foundation Charity Nonprofit organization Other	Dropdown
companyName	Mandatory field. Official registered company name.	Text input
registrationNumber	Mandatory field. Company registration number.	Text input
registrationCountry	Mandatory field. Country of incorporation. Options: all countries list.	Dropdown
legalAddress	Company’s registered legal address.	Text input
taxId	Tax identification number.	Text input
dateOfIncorporation	Company incorporation date.	Date picker
contactNumber	Company contact phone number.	Text input
email	Company contact email address.	Text input

Beneficiaries step

The Beneficiaries step collects information about individuals or companies with roles in the organization. The following fixed roles are supported:

• Shareholder – can be either an individual or another company.

• UBOs (Ultimate Beneficial Owner) – always an individual with ownership/control.

• Director – member of the board.

• Representative – person authorized to act on behalf of the company.

• Other – custom role with mandatory position name.

Step example:

{
  "type": "beneficiaries",
  "key": "beneficiaries",
  "title": { "en": "Beneficiaries" },
  "description": { "en": "Enter information about the company's beneficiaries" },
  "roles": { ... },
  "kycConfigId": "687e0ba12cf633bd323cb0db",
  "kybConfigId": "687e0ba12cf633bd323cb0d2"
}

Step parameters:

Parameter	Description	Type
type	Step type. Must be beneficiaries.	<string>
key	Unique identifier for the step.	<string>
title	Localized title text displayed as the block title to the user. The title can be an <object> containing different languages, allowing the title to be displayed in the selected language during the flow.	<object>
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 flow.	<object>
kycConfigId	ID of the KYC configuration applied to individuals.	<string>
kybConfigId	ID of the KYB configuration applied to companies.	<string>
roles	Defines roles (shareholder, ubo, director, representative, other).	<object>

Role: Shareholder

Can be either an individual or a company.

verification: true → triggers KYC/KYB flows:

• Individual → KYC (kycConfigId)

• Company → KYB (kybConfigId)

Role example:

"roles": {
        "shareholder": {
              "fields": [
                  { "type": "ownershipPercentage", "mandatory": false },
                  { "type": "companyName", "mandatory": true },
                  { "type": "companyEntityType", "mandatory": false },
                  { "type": "registrationNumber", "mandatory": true },
                  { "type": "registrationCountry", "mandatory": true },
                  { "type": "legalAddress", "mandatory": false },
                  { "type": "taxId", "mandatory": false },
                  { "type": "dateOfIncorporation", "mandatory": false },
                  { "type": "firstName", "mandatory": true },
                  { "type": "lastName", "mandatory": true },
                  { "type": "dateOfBirth", "mandatory": true },
                  { "type": "contactNumber", "mandatory": false },
                  { "type": "email", "mandatory": false }, 
                  { "type": "website", "mandatory": false }
              ],
              "verification": true
        }
}

Shareholder fileds:

Field	Description	Input type	Applies to
ownershipPercentage	Percentage of ownership in the company.	Text input	Company / Individual
companyName	Mandatory field. Official registered company name.	Text input	Company
registrationNumber	Mandatory field. Shareholder company registration number.	Text input	Company
registrationCountry	Mandatory field. Country of incorporation. Options: all countries list.	Dropdown	Company
companyEntityType	Mandatory field. Type of legal entity. Options include: Limited liability company Publicly listed company Sole proprietor Partnership Corporation Trust Private foundation Charity Nonprofit organization Other	Dropdown	Company
legalAddress	Registered legal address of shareholder company.	Text input	Company
taxId	Tax identification number.	Text input	Company
dateOfIncorporation	Company incorporation date.	Date picker	Company
website	Company website.	Input	Company
contactNumber	Contact phone number.	Text input	Company / Individual
email	Contact email address.	Text input	Company / Individual
firstName	Mandatory field. Individual's first name.	Text input	Individual
lastName	Mandatory field. Individual's last name.	Text input	Individual
dateOfBirth	Mandatory field. Individual's date of birth.	Date picker	Individual

Role: UBOs

Always an individual.

verification: true → triggers KYC flow for UBOs. (kycConfigId)

Role example:

"roles": {
            "ubo": {
              "fields": [
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "ownershipPercentage", "mandatory": false },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
        }
}

UBOs fields:

Field	Description	Input type
firstName	Mandatory field. Individual's first name.	Text input
lastName	Mandatory field. Individual's last name.	Text input
dateOfBirth	Mandatory field. Individual's date of birth.	Date picker
ownershipPercentage	Percentage of ownership in the company.	Text input
contactNumber	Company contact phone number.	Text input
email	Company contact email address.	Text input

Role: Director

Always an individual.

verification: true → triggers KYC flow for director. (kycConfigId)

Role example:

"roles": {
          "director": {
              "fields": [
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
        }
}

Director fields:

Field	Description	Input type
firstName	Mandatory field. Individual's first name.	Text input
lastName	Mandatory field. Individual's last name.	Text input
dateOfBirth	Mandatory field. Individual's date of birth.	Date picker
contactNumber	Company contact phone number.	Text input
email	Company contact email address.	Text input

Role: Representative

Always an individual.

verification: true → triggers KYC flow for representative. (kycConfigId)

Role example:

"roles": {
          "representative": {
              "fields": [
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
        }
}

Representative fields:

Field	Description	Input type
firstName	Mandatory field. Individual's first name.	Text input
lastName	Mandatory field. Individual's last name.	Text input
dateOfBirth	Mandatory field. Individual's date of birth.	Date picker
contactNumber	Company contact phone number.	Text input
email	Company contact email address.	Text input

Role: Other

Always an individual.

verification: true → triggers KYC flow. (kycConfigId)

Role example:

"roles": {
          "other": {
              "fields": [
                { "type": "positionName", "mandatory": true },
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
        }
}

Fields:

Field	Description	Input type
positionName	Mandatory field. Position title (e.g., advisor)	Text input
firstName	Mandatory field. Individual's first name.	Text input
lastName	Mandatory field. Individual's last name.	Text input
dateOfBirth	Mandatory field. Individual's date of birth.	Date picker
contactNumber	Company contact phone number.	Text input
email	Company contact email address.	Text input

Review step

Final review of the collected company and beneficiary data.

Example:

{
  "type": "kyb-review",
  "key": "kyb-review",
  "title": {
    "en": "Checking the data",
    "es": "Verificando los datos"
  },
  "description": {
    "en": "Please check the information below to make sure everything is correct",
    "es": "Por favor revise la información a continuación para asegurarse de que todo esté correcto"
  }
}

This step allows the applicant to edit the data before submission.

KYB cURL example:

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": [
        {
          "type": "company",
          "key": "company",
          "title": {
            "en": "Company data"
          },
          "description": {
            "en": "Follow the simple steps below"
          },
          "fields": [
               { "type": "companyName", "mandatory": true },
               { "type": "companyEntityType", "mandatory": false },
               { "type": "registrationNumber", "mandatory": true },
               { "type": "registrationCountry", "mandatory": true },
               { "type": "legalAddress", "mandatory": true },
               { "type": "taxId", "mandatory": false },
               { "type": "dateOfIncorporation", "mandatory": false },
               { "type": "contactNumber", "mandatory": false },
               { "type": "email", "mandatory": false }
          ]
        },
        {
          "type": "beneficiaries",
          "key": "beneficiaries",
          "title": {
            "en": "Beneficiaries"
          },
          "description": {
            "en": "Enter information about the company's beneficiaries"
          },
          "kycConfigId": "687e0ba12cf633bd323cb0db",
          "kybConfigId": "687e0ba12cf633bd323cb0d2",
          "roles": {
            "shareholder": {
              "fields": [
                  { "type": "ownershipPercentage", "mandatory": false },
                  { "type": "companyName", "mandatory": true },
                  { "type": "companyEntityType", "mandatory": false },
                  { "type": "registrationNumber", "mandatory": true },
                  { "type": "registrationCountry", "mandatory": true },
                  { "type": "legalAddress", "mandatory": false },
                  { "type": "taxId", "mandatory": false },
                  { "type": "dateOfIncorporation", "mandatory": false },
                  { "type": "firstName", "mandatory": true },
                  { "type": "lastName", "mandatory": true },
                  { "type": "dateOfBirth", "mandatory": true },
                  { "type": "contactNumber", "mandatory": false },
                  { "type": "email", "mandatory": false }, 
                  { "type": "website", "mandatory": false }
              ],
              "verification": true
            },
            "ubo": {
              "fields": [
                { "type": "ownershipPercentage", "mandatory": true },
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
            },
            "director": {
              "fields": [
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
            },
            "representative": {
              "fields": [
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
            },
            "other": {
              "fields": [
                { "type": "positionName", "mandatory": true },
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
            }
          }
        },
        {
          "type": "kyb-review",
          "key": "kyb-review",
          "title": {
            "en": "Checking the data"
          },
          "subtitle": {
            "en": "Please check the information below to make sure everything is correct"
          }
        }
      ]
}'

---

Video call

In the Video call step, the user connects with an operator for a live verification. This can include any of the Identomat verification steps.

Identomat offers two call modes:

• 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	List of steps to run during the video call (except language and operator_questionnaire).	[ ]	<array>
resetSteps	If true, user verification data resets when they rejoin the call.	false	<boolean>
hideCameraOption	Enabling this will hide the camera icon, preventing users from turning off the camera.	false	<boolean>
nameRequired	Requires users to enter their name before joining.	false	<boolean>
multiple_participants	Enables multi-user video sessions.	false	<boolean>

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 or submit their phone number.

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	Requires users to verify their number via an OTP code.	false	<boolean>
require_phone_number	Requires users to submit a phone number without verification.	false	<boolean>

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

The Email step allows users to verify or submit their email address.

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	Requires email verification via an OTP code.	false	<boolean>
require_email	Requires users to submit an email without verification.	false	<boolean>

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 requests the user’s location data by prompting for browser permission.

Geolocation step configurations:

• Type: geolocation

• Key: require_geolocation

• Flags:

  • require_geolocation

Flag	Description	Default	Type
require_geolocation	Requires location access to proceed through the step.	true	<boolean>

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 allows you to collect custom user input as part of the verification flow. It supports various question types and provides multilingual support for titles and descriptions. All responses are saved to the verification session. This step has a slightly different structure compared to other steps.

User questionnaire step configurations:

type

Must be set to "user-questionnaire" to define this step as a user questionnaire block.

key

A client-defined unique key for this questionnaire step. It must remain unique within a single session to avoid conflicts.

title

The main title of the questionnaire displayed on the user interface. Must always be provided as an <object> with language codes as keys (e.g., "en"), even if only one language is used. This ensures consistency and supports future localization.

description

Text displayed beneath the title in the user interface, providing context or instructions. Must always be an <object> of language codes. Same format and rules as title.

questions

An <array> of question objects to be presented to the user. Supported question types include:

• string: Text Input – The user enters a short text answer.

• multiple-choice: : Checkboxes – Allows the user to select one or more options.

• options: Radio – The user selects a single option from a list.

• dropdown : Dropdown List – The user selects one or more options from a dropdown menu.

• file: File Upload – Allows the user to upload a file as a response.

successButtonTitle

Defines the label of the confirmation button displayed at the end of the questionnaire. Must also be an <object> of language codes, even if only one language is used. If any question is marked as "mandatory": true, the button will remain disabled until all required questions are answered.

Questions

Each question in the questions array supports a set of parameters that define how it behaves and appears to the user. Here's a breakdown of all supported properties:

type

Defines the question type.

Supported values:

• string – Short text input

• multiple-choice – Checkbox (multiple selection)

• options– Radio buttons (single selection)

• dropdown– Dropdown menu (single or multi-select)

• file– File upload

title

A multilingual <object> representing the question label.

Example:

"title": {
  "en": "What is your occupation?",
  "fr": "Quelle est votre profession ?"
}

key

A unique identifier for the question within the same questionnaire. This is client-defined and used for referencing and data mapping.

mandatory

Indicates whether the question must be answered before the user can proceed.

• Value: true or false

answer

Allows you to preset an answer for the user.

• string: A plain text string (e.g., "John Doe").

• options: A single option key (e.g., "opt_a").

• multiple-choice: An array of option keys (e.g., ["opt_a", "opt_c"]).

• dropdown: Not applicable.

• file: Not applicable.

Note: End-users can modify pre-filled answers unless readOnly is enabled.

readOnly

Displays the question in a non-editable state. Users can view the question and answer but cannot change it.

• Value: true or false

showConditions

Defines a conditional display rule for the question, based on the answer to a previous question.

"showConditions": {
  "questionKey": "employment-status",
  "answer": "self-employed"
}

• questionKey Key of the controlling question.

• answer Key of the answer (for radio/checkbox) or specific text (for string)

multiple

Specific to dropdown type.

If true, the user can select multiple values from the dropdown.

• Value: true or false

Options

Options are used exclusively in multiple-choice , options and dropdown type questions. They define the selectable choices that the user can pick from.

Each question that supports options must include the following parameter:

options

An <array> of option objects for the question. Each object must include the following:

title

The text label for the option, shown to the user during the verification flow. Must always be provided as an <object> with language codes as keys, even if only one language is used. This ensures consistency across multilingual flows.

Example:

{
  "en": "Self-employed"
}

key

A unique identifier for the option within the questionnaire. This value is used for referencing in preset answers, conditions, and session data. It must be unique within the same questionnaire to avoid conflicts.

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.	-	<string>	"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.	-	<object>	"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.	-	<object>	"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	<boolean>	"mandatory": false
answer	Allows to preset an answer for a question.	-	<string> or <array>	"answer": "option2"
readOnly	Displays the question but restricts interaction.	false	<boolean>	"readOnly": false
showConditions	This parameter may be used to set conditions for whether a question should be displayed.	-	<object>	"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	<object>	"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	-	<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.	-	<string>	"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.	-	<object>	"title": { "es": "Tu título", "en": "Your title" }
mandatory	Specifies whether the question is required to be answered. Possible values: true, false	false	<boolean>	"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.	-	<object>	"answer": { "en": "This is a prefilled answer", "es":"Esta es una respuesta prellenada." }
readOnly	Displays the question but restricts interaction.	false	<boolean>	"readOnly": true
showConditions	This parameter may be used to set conditions for whether a question should be displayed.	-	<object>	"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	-	<string>	"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.	-	<string>	"key": "check-two-answers"
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.	-	<object>	"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	<boolean>	"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	<boolean>	"readOnly": true
showConditions	This parameter may be used to set conditions for whether a question should be displayed.	-	<object>	"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	-	<string>	"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.	-	<string>	"key": "choose-one-answer"
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.	-	<object>	"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	<boolean>	"mandatory": true
answer	Allows to preset an answer for a question. The answer is an <string> of an option key assigned to this question.	-	<string>	"answer": "option-1"
readOnly	Displays the question but restricts interaction.	false	<boolean>	"readOnly": true
showConditions	This parameter may be used to set conditions for whether a question should be displayed.	-	<object>	"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
        }
    ]

---

Question type: Dropdown

Available parameters:

Parameter	Description	Default	Type	Example
type	dropdown	-	<string>	"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.	-	<string>	"key": "choose-from-list"
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.	-	<object>	"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	<boolean>	"mandatory": true
multiple	Specifies whether the question is single or multiple choice. Possible values: true, false	false	<boolean>	"multiple": true
showConditions	This parameter may be used to set conditions for whether a question should be displayed.	-	<object>	"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	-	<string>	"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.	-	<string>	"key": "choose-from-list"
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.	-	<object>	"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.	-	<object>	"description": { "es": "Tu descripción", "en": "Your description" }
mandatory	Specifies whether the question is required to be answered. Possible values: true, false	false	<boolean>	"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.	10	<number>	"filesMaxCount": 5
showConditions	This parameter may be used to set conditions for whether a question should be displayed.	-	<object>	"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

is part of the session and is designed to be filled out by the operator, either during or after the verification call. It allows operators to collect specific information or provide manual input. Its structure closely mirrors the user questionnaire, with the main difference being who completes the form.

Operator questionnaire step configurations:

type

Must be set to "operator-questionnaire" to define this step as an operator-facing form.

key

A unique identifier for the operator questionnaire step. This key is defined by the client and must remain unique within a single session.

title

The name of the section as shown in the operator interface.

Must always be an <object> with language codes as keys, even if only one language is used.

Example:

"title": {
  "en": "Operator notes"
}

description

Text displayed under the title, used to give context or instructions to the operator. Also must be provided as an <object> of language codes.

questions

An <array> of question objects that define the fields the operator will fill out.

Supported question types include:

• string: Text Input – Operator types a short answer as plain text.

• multiple-choice: Checkboxes – Operator selects one or more values from a list.options.

• options: Radio – Operator selects one option from a predefined set.

• dropdown: Dropdown Menu – The operator selects one or more options from a dropdown list, depending on configuration.

• file: File Upload – The operator uploads one or more files (e.g., documents or images) as part of the questionnaire.

Questions

Each question in the Operator Questionnaire must be defined as an object within the questions array. The following parameters are supported for each question:

type

The type of question. Supported values are:

• string – Text Input

• multiple-choice – Checkboxes

• options – Radio Buttons

• dropdown – Dropdown List

• file – File Upload

title

The question title as a string. There are no length or symbol restrictions. The title can also be an The label shown above the question. Must always be provided as an <object> of language codes (e.g., "en", "de"), even if only one language is used.

Example:

"title": {
  "en": "Reason for rejection"
}

key

A unique identifier for the question, defined by the client. It must be unique within the same questionnaire.

mandatory

Boolean. Indicates whether the question must be answered before submitting the questionnaire. Default is false.

answer

Allows you to preset an answer for the operator.

• For string: A plain text string (e.g., "Invalid ID").

• For options: A single option key (e.g., "opt_a").

• For multiple-choice: An array of option keys (e.g., ["opt_a", "opt_c"]).

• For dropdown: Not applicable.

• For file: Not applicable.

Note: Operators can modify pre-filled answers unless readOnly is enabled.

readOnly

Displays the question in a non-editable state. Operators can view the question and answer but cannot change it.

showConditions

Defines a conditional display rule for the question, based on the answer to a previous question.

"showConditions": {
  "questionKey": "employment-status",
  "answer": "self-employed"
}

• questionKey Key of the controlling question.

• answer Key of the answer (for radio/checkbox) or specific text (for string).

Options

Options are used exclusively in multiple-choice , options and dropdown type questions. They define the selectable choices that the user can pick from.

Each question that supports options must include the following parameter:

options

An <array> of option objects for the question. Each object must include the following:

title

The text label for the option, shown to the operator during in the verification session. Must always be provided as an <object> with language codes as keys, even if only one language is used. This ensures consistency across multilingual flows.

{
  "en": "ID card"
}

key

A unique identifier for the option within the questionnaire. This value is used for referencing in preset answers, conditions, and session data. It must be unique within the same questionnaire to avoid conflicts.

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.	-	<string>	"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.	-	<string> or <object>	"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.	-	<string> or <object>	"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	<boolean>	"mandatory": false
answer	Allows to preset an answer for a question.	-	<string> or <array>	"answer": "option2"
readOnly	Displays the question but restricts interaction.	false	<boolean>	"readOnly": false
showConditions	This parameter may be used to set conditions for whether a question should be displayed.	-	<object>	"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"
                        }
                    ]
                }
            ]
        }
    ]
}'

---

Additional session parameters

Besides steps and flags, you can also configure additional parameters when creating a session. These parameters help with session identification and management.

Parameter name	Description	Default	Type
name	A custom session label shown in the dashboard before the user completes verification. Once the session is completed, this value is replaced with the verified user's name (if available).	null	<string>
clientUserId	A unique identifier used to link the session to a specific user in your system. This is useful for grouping sessions or syncing with your internal user or account IDs.	null	<string>
groupId	Defines the group assigned to the session. For example, in a video call, only members of this specified group will be able to receive the call.	null	<string>
scheduleStartTime	The datetime when the session becomes available to the end-user. Before this time, the session cannot be started. Format: ISO 8601 — e.g., "2024-06-20T07:33:00.000Z"	null	<string> (ISO 8601 datetime)
scheduleEndTime	The datetime after which the session is no longer accessible to the end-user. Format: ISO 8601 — e.g., "2024-06-20T09:00:00.000Z"	null	<string> (ISO 8601 datetime)

Example:

{
  "name": "KYC for John Smith",
  "clientUserId": "user-12345",
  "groupId": "682c60525a91a1e5b473858d",
  "scheduleStartTime": "2024-06-20T07:33:00.000Z",
  "scheduleEndTime": "2024-06-20T09:00:00.000Z",
  "steps": [...],
  "flags": [...]
}