# KYB (Know Your Business)

The **KYB flow** is designed to collect and verify company information, including details about the organization itself, its beneficiaries, and its representatives.\
It ensures that all relevant entities are identified and verified before completing the onboarding process.

The KYB flow consists of three main steps: 

{% stepper %}
{% step %}
[Company data](#company-data)
{% endstep %}

{% step %}
[Beneficiaries](#beneficiaries)
{% endstep %}

{% step %}
[Review](#review)
{% endstep %}
{% endstepper %}

Each step is fully configurable and can include its own parameters.

## Flags

`flags` is an object that contains optional configuration parameters for adjusting the KYB verification flow.\
Below is a summary of the most commonly used flags:

<table data-full-width="true"><thead><tr><th width="218">Flag name</th><th width="437">Description</th><th width="216">Default</th><th width="121">Type</th></tr></thead><tbody><tr><td><code>skip_face</code></td><td>Skips the <code>liveness</code> step if it already exists in the defined steps. Prevents duplication when using custom flows.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>skip_document</code></td><td>Skips the <code>identity-document</code> step if it already exists in the defined steps. Prevents duplication when using custom flows.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>return_url</code></td><td>URL to redirect the user to after the identification process is completed. If omitted, the session is assumed to be embedded in an iframe.</td><td><code>null</code></td><td>&#x3C;string></td></tr><tr><td><code>language</code></td><td><p>User interface language code. Supported values:</p><pre data-overflow="wrap"><code>"es", "ka", "uk", "ru", "uz", "it", "gr", "tr", "ro", "ar", "de", "pl", "hi", "bn", "az", "ja", "pt", "fr", "kk", "sv"
</code></pre><p></p></td><td><code>"en"</code></td><td>&#x3C;string></td></tr><tr><td><code>skip_desktop</code></td><td>Limits sessions to mobile devices only. If initiated on desktop, a QR code is shown to transfer the session to a mobile device.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>switch_device_url</code></td><td>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.</td><td><code>null</code></td><td>&#x3C;string></td></tr><tr><td><code>restrict_url_sharing</code></td><td>Prevents the session URL from being used on a different browser or device. <br>If <code>true</code>, the QR code will not appear when camera access is denied—unless <code>switch_device_url</code> is also defined.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr></tbody></table>

## Steps

The `steps` array defines the sequence and structure of the KYB process. It is passed together with the `company_key` and `flags` parameters when creating a session.

Each step in the array can contain its own properties properties:

<table><thead><tr><th width="163.91015625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>The type of the specific step (see list of supported step types below).</td></tr><tr><td><code>key</code></td><td>A unique identifier for the step. This key can be customized but must remain unique within the session.</td></tr><tr><td><code>flags</code></td><td>Step-specific configuration flags that control the behavior of this step.</td></tr><tr><td><code>title</code></td><td>A custom title provided by the client, displayed to the user during this step in the interface.</td></tr></tbody></table>

### **Supported step types**

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

* [Language](#language)
* [Company data](#company-data)
* [Beneficiaries](#beneficiaries)
* [Review](#review)
* [User questionnaire](#user-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`&#x20;

<table data-full-width="true"><thead><tr><th width="259">Flag</th><th width="448">Description</th><th width="109.34765625">Default</th><th width="130.85546875">Type</th></tr></thead><tbody><tr><td><code>languages</code></td><td><p>An array of language codes to display. If left empty, all supported languages will be shown.</p><pre data-overflow="wrap"><code>"en", "ka", "es", "uk", "gr", "it", "de", "ru", "uz", "ro", "tr", "ar", "pl", "bn", "hi", "hy", "az", "ja", "pt", "fr", "kk", "sv"
</code></pre></td><td>All</td><td>Array&#x3C;string></td></tr></tbody></table>

<details>

<summary><em>Expand to view example</em></summary>

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

</details>

***

### Company data

This step collects the core information about the company.

* **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:**

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

**Step parameters:**

<table data-full-width="true"><thead><tr><th width="224.7890625">Parameter</th><th width="632.81640625">Description</th><th width="121">Type</th></tr></thead><tbody><tr><td><code>type</code></td><td>Step type. Must be <code>company</code>.</td><td>&#x3C;string></td></tr><tr><td><code>key</code></td><td>Unique identifier for the step.</td><td>&#x3C;string></td></tr><tr><td><code>title</code></td><td>Localized title text displayed as the block title to the user. The title can be an &#x3C;object> containing different <strong>languages</strong>, allowing the title to be displayed in the selected language during the flow.</td><td>&#x3C;object></td></tr><tr><td><code>description</code></td><td>A description that appears below the title on the user's side. Similar to the title, the description can be an &#x3C;object> containing different <strong>languages</strong>, so that it can be displayed in the selected language during the flow.</td><td>&#x3C;object></td></tr><tr><td><code>fields</code></td><td>List of fields to be collected during this step.</td><td>&#x3C;array></td></tr></tbody></table>

**Fields:**

Example:

```json
"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 }
              ]
```

<table data-full-width="true"><thead><tr><th width="237.4921875">Field</th><th width="593.64453125">Description</th><th width="195.2734375">Input type</th></tr></thead><tbody><tr><td><code>companyEntityType</code></td><td><p><strong>Mandatory field.</strong> </p><p>Type of legal entity. Options include:</p><p></p><ul><li>Limited liability company</li><li>Publicly listed company</li><li>Sole proprietor</li><li>Partnership</li><li>Corporation</li><li>Trust</li><li>Private foundation</li><li>Charity</li><li>Nonprofit organization</li><li>Other</li></ul></td><td>Dropdown</td></tr><tr><td><code>companyName</code></td><td><p><strong>Mandatory field.</strong> </p><p>Official registered company name.</p></td><td>Text input</td></tr><tr><td><code>registrationNumber</code></td><td><p><strong>Mandatory field.</strong> </p><p>Company registration number.</p></td><td>Text input</td></tr><tr><td><code>registrationCountry</code></td><td><strong>Mandatory field.</strong> <br>Country of incorporation. Options: all countries list.</td><td>Dropdown</td></tr><tr><td><code>legalAddress</code></td><td>Company’s registered legal address.</td><td>Text input</td></tr><tr><td><code>taxId</code></td><td>Tax identification number.</td><td>Text input</td></tr><tr><td><code>dateOfIncorporation</code></td><td>Company incorporation date.</td><td>Date picker</td></tr><tr><td><code>contactNumber</code></td><td>Company contact phone number.</td><td>Text input</td></tr><tr><td><code>email</code></td><td>Company contact email address.</td><td>Text input</td></tr></tbody></table>

***

### Beneficiaries

The **Beneficiaries step** collects information about all individuals or companies with roles in the organization.

Each role can trigger either a KYC or KYB verification flow.

**Supported roles:**

* **Shareholder** – can be either an individual or another company
* **UBOs (Ultimate Beneficial Owner)** – always an individual with ownership/control
* **Director** – individual member of the board
* **Representative** – authorized individual acting on behalf of the company
* **Other** – custom role (requires position name)

**Step example:**

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

**Step parameters:**

<table data-full-width="true"><thead><tr><th width="257.1328125">Parameter</th><th width="540.40234375">Description</th><th width="198.234375">Type</th></tr></thead><tbody><tr><td><code>type</code></td><td>Step type. Must be <code>beneficiaries</code>.</td><td>&#x3C;string></td></tr><tr><td><code>key</code></td><td>Unique identifier for the step.</td><td>&#x3C;string></td></tr><tr><td><code>title</code></td><td>Localized title text displayed as the block title to the user. The title can be an &#x3C;object> containing different <strong>languages</strong>, allowing the title to be displayed in the selected language during the flow.</td><td>&#x3C;object></td></tr><tr><td><code>description</code></td><td>A description that appears below the title on the user's side. Similar to the title, the description can be an &#x3C;object> containing different <strong>languages</strong>, so that it can be displayed in the selected language during the flow.</td><td>&#x3C;object></td></tr><tr><td><code>kycConfigId</code></td><td>ID of the KYC configuration applied to individuals.</td><td>&#x3C;string></td></tr><tr><td><code>kybConfigId</code></td><td>ID of the KYB configuration applied to companies.</td><td>&#x3C;string></td></tr><tr><td><code>roles</code></td><td>Defines roles (<code>shareholder</code>, <code>ubo</code>, <code>director</code>, <code>representative</code>, <code>other</code>).</td><td>&#x3C;object></td></tr></tbody></table>

#### **Role: Shareholder**

* Can be either an **individual** or a **company**.
* `verification: true` → triggers a verification flow
  * **Individual** → KYC (`kycConfigId`)
  * **Company** → KYB (`kybConfigId`)

**Important:**\
Pre-created KYC and KYB configurations are required for shareholder verification flows.\
These configurations define which verification steps (e.g., document upload, selfie, questionnaire) will be applied during the process. \
To learn how to create and manage KYC configurations, refer to the [KYC developer's guide](https://docs.identomat.com/developer-tools/developer-guide/kyc-know-your-customer) or [KYC configuration guide](https://docs.identomat.com/no-code-workflows/kyc-steps).

**Role example:**

```json
"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:**

<table data-full-width="true"><thead><tr><th width="237.4921875">Field</th><th width="484.6484375">Description</th><th width="111.6953125">Input type</th><th>Applies to</th></tr></thead><tbody><tr><td><code>ownershipPercentage</code></td><td>Percentage of ownership in the company.</td><td>Text input</td><td>Company / Individual</td></tr><tr><td><code>companyName</code></td><td><p><strong>Mandatory field.</strong> </p><p>Official registered company name.</p></td><td>Text input</td><td>Company</td></tr><tr><td><code>registrationNumber</code></td><td><p><strong>Mandatory field.</strong> </p><p>Shareholder company registration number.</p></td><td>Text input</td><td>Company</td></tr><tr><td><code>registrationCountry</code></td><td><strong>Mandatory field.</strong> <br>Country of incorporation. Options: all countries list.</td><td>Dropdown</td><td>Company</td></tr><tr><td><code>companyEntityType</code></td><td><p><strong>Mandatory field.</strong> </p><p>Type of legal entity. Options include:</p><p></p><ul><li>Limited liability company</li><li>Publicly listed company</li><li>Sole proprietor</li><li>Partnership</li><li>Corporation</li><li>Trust</li><li>Private foundation</li><li>Charity</li><li>Nonprofit organization</li><li>Other</li></ul></td><td>Dropdown</td><td>Company</td></tr><tr><td><code>legalAddress</code></td><td>Registered legal address of shareholder company.</td><td>Text input</td><td>Company</td></tr><tr><td><code>taxId</code></td><td>Tax identification number.</td><td>Text input</td><td>Company</td></tr><tr><td><code>dateOfIncorporation</code></td><td>Company incorporation date.</td><td>Date picker</td><td>Company</td></tr><tr><td><code>website</code></td><td>Company website.</td><td>Input</td><td>Company</td></tr><tr><td><code>contactNumber</code></td><td>Contact phone number.</td><td>Text input</td><td>Company / Individual</td></tr><tr><td><code>email</code></td><td>Contact email address.</td><td>Text input</td><td>Company / Individual</td></tr><tr><td><code>firstName</code></td><td><strong>Mandatory field.</strong> <br>Individual's first name.</td><td>Text input</td><td>Individual</td></tr><tr><td><code>lastName</code></td><td><strong>Mandatory field.</strong> <br>Individual's last name.</td><td>Text input</td><td>Individual</td></tr><tr><td><code>dateOfBirth</code></td><td><strong>Mandatory field.</strong> <br>Individual's date of birth.</td><td>Date picker</td><td>Individual</td></tr></tbody></table>

#### **Role: UBOs**

* Always an **individual**.
* `verification: true` → triggers KYC flow (`kycConfigId`)

**Important:**\
Pre-created KYC configuration is required for UBOs verification flows.\
These configurations define which verification steps (e.g., document upload, selfie, questionnaire) will be applied during the process. \
To learn how to create and manage KYC configurations, refer to the [KYC developer's guide](https://docs.identomat.com/developer-tools/developer-guide/kyc-know-your-customer) or [KYC configuration guide](https://docs.identomat.com/no-code-workflows/kyc-steps).

**Role example:**

```json
"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:**

<table data-full-width="true"><thead><tr><th>Field</th><th>Description</th><th>Input type</th></tr></thead><tbody><tr><td><code>firstName</code></td><td><strong>Mandatory field.</strong> <br>Individual's first name.</td><td>Text input</td></tr><tr><td><code>lastName</code></td><td><strong>Mandatory field.</strong> <br>Individual's last name.</td><td>Text input</td></tr><tr><td><code>dateOfBirth</code></td><td><strong>Mandatory field.</strong> <br>Individual's date of birth.</td><td>Date picker</td></tr><tr><td><code>ownershipPercentage</code></td><td>Percentage of ownership in the company.</td><td>Text input</td></tr><tr><td><code>contactNumber</code></td><td>Company contact phone number.</td><td>Text input</td></tr><tr><td><code>email</code></td><td>Company contact email address.</td><td>Text input</td></tr></tbody></table>

#### **Role: Director**

* Always an **individual**.
* `verification: true` → triggers KYC flow (`kycConfigId`)

**Important:**\
Pre-created KYC configuration is required for Director verification flows.\
These configurations define which verification steps (e.g., document upload, selfie, questionnaire) will be applied during the process. \
To learn how to create and manage KYC configurations, refer to the [KYC developer's guide](https://docs.identomat.com/developer-tools/developer-guide/kyc-know-your-customer) or [KYC configuration guide](https://docs.identomat.com/no-code-workflows/kyc-steps).

**Role example:**

```json
"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:**

<table data-full-width="true"><thead><tr><th>Field</th><th>Description</th><th>Input type</th></tr></thead><tbody><tr><td><code>firstName</code></td><td><strong>Mandatory field.</strong> <br>Individual's first name.</td><td>Text input</td></tr><tr><td><code>lastName</code></td><td><strong>Mandatory field.</strong> <br>Individual's last name.</td><td>Text input</td></tr><tr><td><code>dateOfBirth</code></td><td><strong>Mandatory field.</strong> <br>Individual's date of birth.</td><td>Date picker</td></tr><tr><td><code>contactNumber</code></td><td>Company contact phone number.</td><td>Text input</td></tr><tr><td><code>email</code></td><td>Company contact email address.</td><td>Text input</td></tr></tbody></table>

#### **Role: Representative**

* Always an **individual**.
* `verification: true` → triggers KYC flow (`kycConfigId`)

**Important:**\
Pre-created KYC configuration is required for Representative verification flows.\
These configurations define which verification steps (e.g., document upload, selfie, questionnaire) will be applied during the process. \
To learn how to create and manage KYC configurations, refer to the [KYC developer's guide](https://docs.identomat.com/developer-tools/developer-guide/kyc-know-your-customer) or [KYC configuration guide](https://docs.identomat.com/no-code-workflows/kyc-steps).

**Role example:**

```json
"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:**

<table data-full-width="true"><thead><tr><th>Field</th><th>Description</th><th>Input type</th></tr></thead><tbody><tr><td><code>firstName</code></td><td><strong>Mandatory field.</strong> <br>Individual's first name.</td><td>Text input</td></tr><tr><td><code>lastName</code></td><td><strong>Mandatory field.</strong> <br>Individual's last name.</td><td>Text input</td></tr><tr><td><code>dateOfBirth</code></td><td><strong>Mandatory field.</strong> <br>Individual's date of birth.</td><td>Date picker</td></tr><tr><td><code>contactNumber</code></td><td>Company contact phone number.</td><td>Text input</td></tr><tr><td><code>email</code></td><td>Company contact email address.</td><td>Text input</td></tr></tbody></table>

#### **Role: Other**

* Always an **individual**.
* `verification: true` → triggers KYC flow (`kycConfigId`)

**Important:**\
Pre-created KYC configuration is required for Other role verification flows.\
These configurations define which verification steps (e.g., document upload, selfie, questionnaire) will be applied during the process. \
To learn how to create and manage KYC configurations, refer to the [KYC developer's guide](https://docs.identomat.com/developer-tools/developer-guide/kyc-know-your-customer) or [KYC configuration guide](https://docs.identomat.com/no-code-workflows/kyc-steps).

**Role example:**

```json
"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:**

<table data-full-width="true"><thead><tr><th>Field</th><th>Description</th><th>Input type</th></tr></thead><tbody><tr><td><code>positionName</code></td><td><strong>Mandatory field.</strong> <br>Position title (e.g., advisor)</td><td>Text input</td></tr><tr><td><code>firstName</code></td><td><strong>Mandatory field.</strong> <br>Individual's first name.</td><td>Text input</td></tr><tr><td><code>lastName</code></td><td><strong>Mandatory field.</strong> <br>Individual's last name.</td><td>Text input</td></tr><tr><td><code>dateOfBirth</code></td><td><strong>Mandatory field.</strong> <br>Individual's date of birth.</td><td>Date picker</td></tr><tr><td><code>contactNumber</code></td><td>Company contact phone number.</td><td>Text input</td></tr><tr><td><code>email</code></td><td>Company contact email address.</td><td>Text input</td></tr></tbody></table>

***

### Review

The **Review** step presents a summary of all collected company and beneficiary data before submission. Applicants can review and edit information if needed.

Example:

```json
{
  "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:

<details>

<summary><em>Expand to view example</em></summary>

```bash
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"
          }
        }
      ]
}'
```

</details>

***

### 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`: **Short answer** – 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.
  * `attachment`: **Attachment -** Allows attaching files either dynamically (via API/configuration) or per session. Depending on configuration, files may be pre-attached for the user or uploaded by the operator during the session.
* `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
  * `attachment` - Attach files and share with the end-user
* `title`\
  A multilingual \<object> representing the question label.\
  Example:

```json
"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.
  * `attachment`: An array of file IDs

  *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.
  * `questionKey`  Key of the controlling question.
  * `answer`  Key of the answer (for radio/checkbox) or specific text (for string)

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

* `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:

```json
{
  "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:**

<table data-full-width="true"><thead><tr><th width="133">Parameter</th><th width="217">Description</th><th width="100">Default</th><th width="118">Type</th><th>Example</th></tr></thead><tbody><tr><td><code>key</code></td><td><p>Keys are chosen by the client and must remain unique within a single session.</p><p>Recommended to use key describing the questionnaire shortly. </p></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"key": "terms-and-conditions"
</code></pre></td></tr><tr><td><code>title</code></td><td>The title of the user questionnaire, displayed as the block title on the user's side. The title can be an &#x3C;object> containing different <strong>languages</strong>, allowing the title to be displayed in the selected language during the verification flow.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"title": { 
    "es": "Tu título",
    "en": "Your title"
}
</code></pre></td></tr><tr><td><code>description</code></td><td>A description that appears below the title on the user's side. Similar to the title, the description can be an &#x3C;object> containing different <strong>languages</strong>, so that it can be displayed in the selected language during the verification flow.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"description": {
    "es": "Tu descripción",
    "en": "Your description"
}
</code></pre></td></tr><tr><td><code>questions</code></td><td>An &#x3C;array>  of questions with the following types: <code>string</code>, <code>multiple-choice</code> , <code>options</code>, <code>dropdown</code>.</td><td>-</td><td>&#x3C;array></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"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"
        }
    ]
    }
]
</code></pre></td></tr><tr><td><code>mandatory</code></td><td><p>Specifies whether the question is required to be answered.<br></p><p>Possible values:</p><p><code>true</code>, <code>false</code></p></td><td>false</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"mandatory": false
</code></pre></td></tr><tr><td><code>answer</code></td><td>Allows to preset an answer for a question.</td><td>-</td><td>&#x3C;string> or &#x3C;array></td><td><pre class="language-json"><code class="lang-json">"answer": "option2"
</code></pre></td></tr><tr><td><code>readOnly</code></td><td>Displays the question but restricts interaction.</td><td>false</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"readOnly": false
</code></pre></td></tr><tr><td><code>showConditions</code></td><td>This parameter may be used to set conditions for whether a question should be displayed.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }
</code></pre></td></tr><tr><td><code>successButtonTitle</code></td><td>The title of the action button in the questionnaire. If the questions are mandatory, the button is deactivated until the user completes the questionnaire.</td><td>Confirm</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"successButtonTitle": { 
    "es": "Tu título",
    "en": "Your title"
}
</code></pre></td></tr></tbody></table>

#### **cURL example:**

<details>

<summary><em>Expand to view user-questionnaire example</em></summary>

<pre class="language-bash"><code class="lang-bash">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"
<strong>                },
</strong>            "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"
                    }
                ]
            }
        ]
    }
]
}'
</code></pre>

</details>

#### **Question type: Short answer**

Available parameters:&#x20;

<table data-full-width="true"><thead><tr><th width="133">Parameter</th><th width="217">Description</th><th width="100">Default</th><th width="118">Type</th><th>Example</th></tr></thead><tbody><tr><td><code>type</code></td><td><code>string</code></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json"><code class="lang-json">"type": "string"
</code></pre></td></tr><tr><td><code>key</code></td><td><p>Keys are chosen by the client and must remain unique within a single session.</p><p>Recommended to use key describing the question shortly. </p></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"key": "your-address"
</code></pre></td></tr><tr><td><code>title</code></td><td>The title is an  &#x3C;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.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"title": { 
    "es": "Tu título",
    "en": "Your title"
}
</code></pre></td></tr><tr><td><code>mandatory</code></td><td><p>Specifies whether the question is required to be answered.<br></p><p>Possible values:</p><p><code>true</code>, <code>false</code></p></td><td>false</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"mandatory": true
</code></pre></td></tr><tr><td><code>format</code></td><td>Specifies the expected structure of the user’s response. Determines how the input is validated.</td><td><code>free-text</code></td><td>&#x3C;object></td><td><pre class="language-json"><code class="lang-json">"format": {
    "type": "free-text"
}
</code></pre><pre class="language-json"><code class="lang-json">"format": {
    "type": "email"
}
</code></pre></td></tr><tr><td><code>answer</code></td><td>Allows to preset an answer for a question.<br>The answer is an  &#x3C;object> of languages so that if the user changes the language during the verification flow, the prefilled answer can be displayed in different languages.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"answer": { 
        "en": "This is a prefilled answer",
        "es":"Esta es una respuesta prellenada."
}
</code></pre></td></tr><tr><td><code>readOnly</code></td><td>Displays the question but restricts interaction.</td><td>false</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"readOnly": true
</code></pre></td></tr><tr><td><code>showConditions</code></td><td>This parameter may be used to set conditions for whether a question should be displayed.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }
</code></pre></td></tr></tbody></table>

<details>

<summary><em>Expand to view SHORT ANSWER question example</em></summary>

```json
"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
    }
]
```

</details>

***

#### **Question type: Checkbox**

Available parameters:&#x20;

<table data-full-width="true"><thead><tr><th width="133">Parameter</th><th width="217">Description</th><th width="100">Default</th><th width="118">Type</th><th>Example</th></tr></thead><tbody><tr><td><code>type</code></td><td><code>multiple-choice</code></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json"><code class="lang-json">"type": "multiple-choice"
</code></pre></td></tr><tr><td><code>key</code></td><td><p>Keys are chosen by the client and must remain unique within a single session.</p><p>Recommended to use key describing the question shortly. </p></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"key": "check-two-answers"
</code></pre></td></tr><tr><td><code>title</code></td><td>The title is an  &#x3C;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.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"title": { 
    "es": "Tu título",
    "en": "Your title"
}
</code></pre></td></tr><tr><td><code>options</code></td><td><p></p><p>An &#x3C;array> of options for the question. Each option may have:</p><ul><li>"<strong>title</strong>" : The title of an option. The title is an &#x3C;object> containing different languages, allowing the option to be displayed in the selected language during the verification flow.</li><li>"<strong>key</strong>": The key for the option, chosen by the client. It must remain unique within a single questionnaire.</li></ul></td><td>-</td><td>&#x3C;array></td><td><p></p><pre class="language-json" data-overflow="wrap"><code class="lang-json">"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"
    ]
</code></pre></td></tr><tr><td><code>mandatory</code></td><td><p>Specifies whether the question is required to be answered.<br></p><p>Possible values:</p><p><code>true</code>, <code>false</code></p></td><td>false</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"mandatory": true
</code></pre></td></tr><tr><td><code>answer</code></td><td>Allows to preset an answer for a question.<br>The answer is an  &#x3C;array> <strong>of option keys</strong> assigned to this question.</td><td>-</td><td>&#x3C;array></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"answer": [
    "option-1",
    "option-2"
]
</code></pre></td></tr><tr><td><code>readOnly</code></td><td>Displays the question but restricts interaction.</td><td>false</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"readOnly": true
</code></pre></td></tr><tr><td><code>showConditions</code></td><td>This parameter may be used to set conditions for whether a question should be displayed.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }
</code></pre></td></tr></tbody></table>

<details>

<summary><em>Expand to view CHECKBOX question example</em></summary>

```json
"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
        }
    ]
```

</details>

***

#### **Question type: Radio**

Available parameters:&#x20;

<table data-full-width="true"><thead><tr><th width="133">Parameter</th><th width="217">Description</th><th width="100">Default</th><th width="118">Type</th><th>Example</th></tr></thead><tbody><tr><td><code>type</code></td><td><code>options</code></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json"><code class="lang-json">"type": "options"
</code></pre></td></tr><tr><td><code>key</code></td><td><p>Keys are chosen by the client and must remain unique within a single session.</p><p>Recommended to use key describing the question shortly. </p></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"key": "choose-one-answer"
</code></pre></td></tr><tr><td><code>title</code></td><td>The title is an  &#x3C;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.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"title": { 
    "es": "Tu título",
    "en": "Your title"
}
</code></pre></td></tr><tr><td><code>options</code></td><td><p></p><p>An &#x3C;array> of options for the question. Each option may have:</p><ul><li>"<strong>title</strong>" : The title of an option. The title is an &#x3C;object> containing different languages, allowing the option to be displayed in the selected language during the verification flow.</li><li>"<strong>key</strong>": The key for the option, chosen by the client. It must remain unique within a single questionnaire.</li></ul></td><td>-</td><td>&#x3C;array></td><td><p></p><pre class="language-json" data-overflow="wrap"><code class="lang-json">"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"
    ]
</code></pre></td></tr><tr><td><code>mandatory</code></td><td><p>Specifies whether the question is required to be answered.<br></p><p>Possible values:</p><p><code>true</code>, <code>false</code></p></td><td>false</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"mandatory": true
</code></pre></td></tr><tr><td><code>answer</code></td><td>Allows to preset an answer for a question.<br>The answer is an  &#x3C;string> <strong>of an option key</strong> assigned to this question.</td><td>-</td><td>&#x3C;string></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"answer": "option-1"
</code></pre></td></tr><tr><td><code>readOnly</code></td><td>Displays the question but restricts interaction.</td><td>false</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"readOnly": true
</code></pre></td></tr><tr><td><code>showConditions</code></td><td>This parameter may be used to set conditions for whether a question should be displayed.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }
</code></pre></td></tr></tbody></table>

<details>

<summary><em>Expand to view RADIO question example</em></summary>

```json
"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
        }
    ]
```

</details>

***

#### **Question type: Dropdown**

Available parameters:&#x20;

<table data-full-width="true"><thead><tr><th width="133">Parameter</th><th width="217">Description</th><th width="100">Default</th><th width="118">Type</th><th>Example</th></tr></thead><tbody><tr><td><code>type</code></td><td><code>dropdown</code></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json"><code class="lang-json">"type": "dropdown"
</code></pre></td></tr><tr><td><code>key</code></td><td><p>Keys are chosen by the client and must remain unique within a single session.</p><p>Recommended to use key describing the question shortly. </p></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"key": "choose-from-list"
</code></pre></td></tr><tr><td><code>title</code></td><td>The title is an  &#x3C;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.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"title": { 
    "es": "Tu título",
    "en": "Your title"
}
</code></pre></td></tr><tr><td><code>options</code></td><td><p></p><p>An &#x3C;array> of options for the question. Each option may have:</p><ul><li>"<strong>title</strong>" : The title of an option. The title is an &#x3C;object> containing different languages, allowing the option to be displayed in the selected language during the verification flow.</li><li>"<strong>key</strong>": The key for the option, chosen by the client. It must remain unique within a single questionnaire.</li></ul></td><td>-</td><td>&#x3C;array></td><td><p></p><pre class="language-json" data-overflow="wrap"><code class="lang-json">"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"
    ]
</code></pre></td></tr><tr><td><code>mandatory</code></td><td><p>Specifies whether the question is required to be answered.<br></p><p>Possible values:</p><p><code>true</code>, <code>false</code></p></td><td>false</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"mandatory": true
</code></pre></td></tr><tr><td><code>multiple</code></td><td><p>Specifies whether the question is single or multiple choice.</p><p></p><p>Possible values:</p><p><code>true</code>, <code>false</code></p></td><td>false</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"multiple": true
</code></pre></td></tr><tr><td><code>showConditions</code></td><td>This parameter may be used to set conditions for whether a question should be displayed.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }
</code></pre></td></tr></tbody></table>

<details>

<summary><em>Expand to view DROPDOWN question example</em></summary>

```json
"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"
            }
        }
    ]
```

</details>

***

#### **Question type: File upload**

Available parameters:&#x20;

<table data-full-width="true"><thead><tr><th width="133">Parameter</th><th width="217">Description</th><th width="100">Default</th><th width="118">Type</th><th>Example</th></tr></thead><tbody><tr><td><code>type</code></td><td><code>file</code></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json"><code class="lang-json">"type": "file"
</code></pre></td></tr><tr><td><code>key</code></td><td><p>Keys are chosen by the client and must remain unique within a single session.</p><p>Recommended to use key describing the question shortly. </p></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"key": "choose-from-list"
</code></pre></td></tr><tr><td><code>title</code></td><td>The title is an  <code>&#x3C;object></code> 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.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"title": { 
    "es": "Tu título",
    "en": "Your title"
}
</code></pre></td></tr><tr><td><code>description</code></td><td>A description that appears below the title. Similar to the title, the description can be an &#x3C;object> containing different languages, so that it can be displayed in the selected language during the verification flow.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json"><code class="lang-json">"description": {
    "es": "Tu descripción",
    "en": "Your description"
}
</code></pre></td></tr><tr><td><code>mandatory</code></td><td><p>Specifies whether the question is required to be answered.<br></p><p>Possible values:</p><p><code>true</code>, <code>false</code></p></td><td>false</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"mandatory": true
</code></pre></td></tr><tr><td><code>fileTypes</code></td><td>Specifies the types of files the user is allowed to upload.<br><br>Possible values:<br> <code>pdf</code>, <code>image</code>.</td><td>[ <code>"pdf"</code>, <code>"image"</code> ]</td><td>&#x3C;array></td><td><p></p><pre class="language-json"><code class="lang-json">"fileTypes": [
    "pdf",
    "image"
]
</code></pre></td></tr><tr><td><code>filesMaxCount</code></td><td>Specifies the maximum number of files the user is allowed to upload.<br><br>Possible values:<br>A number from 1 to 10.</td><td>10</td><td>&#x3C;number></td><td><pre class="language-json"><code class="lang-json">"filesMaxCount": 5
</code></pre></td></tr><tr><td><code>showConditions</code></td><td>This parameter may be used to set conditions for whether a question should be displayed.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json5" data-overflow="wrap"><code class="lang-json5">"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }
</code></pre></td></tr></tbody></table>

<details>

<summary><em>Expand to view FILE UPLOAD question example</em></summary>

```json
"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"
            }
        }
    ]
```

</details>

***

#### **Question type: Attachment**

The **Attachment** question type allows attaching files to a questionnaire. It supports two main use cases:

1. **Operator-added attachments per session**\
   The operator uploads files during or before the verification session and shares them with the end-user.
2. **Predefined attachments from Configuration or API**\
   Files are uploaded in the Configuration interface or dynamically provided via API. These files are automatically included in future sessions.

**Behavior**

* Attachments are visible to both the operator and the end-user.
* When files are provided via API (`answer`) or Configuration, they will appear when the questionnaire is opened.
* Depending on settings, the operator may be allowed or restricted from modifying attachments after the user has confirmed the questionnaire.

Available parameters:&#x20;

<table data-full-width="true"><thead><tr><th width="133">Parameter</th><th width="217">Description</th><th width="100">Default</th><th width="118">Type</th><th>Example</th></tr></thead><tbody><tr><td><code>type</code></td><td><code>attachment</code></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json"><code class="lang-json">"type": "attachment"
</code></pre></td></tr><tr><td><code>key</code></td><td><p>Keys are chosen by the client and must remain unique within a single session.</p><p>Recommended to use key describing the question shortly. </p></td><td>-</td><td>&#x3C;string></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"key": "attached-documents"
</code></pre></td></tr><tr><td><code>title</code></td><td>The title is an  <code>&#x3C;object></code> 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.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"title": { 
    "es": "Tu título",
    "en": "Your title"
}
</code></pre></td></tr><tr><td><code>description</code></td><td>A description that appears below the title. Similar to the title, the description can be an &#x3C;object> containing different languages, so that it can be displayed in the selected language during the verification flow.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json"><code class="lang-json">"description": {
    "es": "Tu descripción",
    "en": "Your description"
}
</code></pre></td></tr><tr><td><code>fileTypes</code></td><td>Specifies the types of files the user is allowed to upload.<br><br>Possible values:<br> <code>pdf</code>, <code>image</code>.</td><td>[ <code>"pdf"</code>, <code>"image"</code> ]</td><td>&#x3C;array></td><td><p></p><pre class="language-json"><code class="lang-json">"fileTypes": [
    "pdf",
    "image"
]
</code></pre></td></tr><tr><td><code>filesMaxCount</code></td><td>Specifies the maximum number of files the user is allowed to upload.<br><br>Possible values:<br>A number from 1 to 10.</td><td>10</td><td>&#x3C;number></td><td><pre class="language-json"><code class="lang-json">"filesMaxCount": 5
</code></pre></td></tr><tr><td><code>showConditions</code></td><td>This parameter may be used to set conditions for whether a question should be displayed.</td><td>-</td><td>&#x3C;object></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }
</code></pre></td></tr><tr><td><code>allowOperatorUpload</code></td><td>Controls how files are added:<br>• <strong>true</strong> – operator uploads files per session.<br>• <strong>false</strong> – files are provided via Configuration or API only.</td><td>true</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"allowOperatorUpload": true
</code></pre></td></tr><tr><td><code>allowOperatorOverride</code></td><td>If <strong>false</strong>, the operator cannot edit attachments after the user confirms the questionnaire. <br>If <strong>true</strong>, the operator may still upload or remove files.</td><td>true</td><td>&#x3C;boolean></td><td><pre class="language-json"><code class="lang-json">"allowOperatorOverride": true
</code></pre></td></tr></tbody></table>

<details>

<summary><em>Expand to view ATTACHMENT question example</em></summary>

```json
"questions": [
    {
        "type": "attachment",
        "title": {
            "es": "Tu título",
            "en": "Your title"
        },
        "description": {
            "es": "Tu descripción",
            "en": "Your description"
            },
        "key": "question5",
        "fileTypes": [
            "pdf",
            "image"
            ],
        "filesMaxCount": 5,
        "allowOperatorUpload": true,
        "allowOperatorOverride": true,
        "answer": [ ],
        "showConditions": {
            "questionKey": "question1",
            "answer": "option1"
            }
        }
    ]
```

</details>