# KYC (Know Your Customer)

Each KYC verification flow consists of configurable steps that define how the end user’s identity is verified. The flags and steps listed below determine which checks are included in the process and how they are executed.

## Flags

The `flags`  is an object with optional configuration flags that adjust the KYC 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><tr><td><code>requireHdMedia</code></td><td>Enforces Full HD (1080p+) camera usage for <code>liveness</code> and <code>identity-document</code> steps. If not met, a QR code is shown for the user to switch to another device.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr></tbody></table>

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

<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)
* [ID verification](#identity-document-verification)
* [Liveness check](#liveness-check)
* [Proof of Address](#proof-of-address)
* [Selfie with ID](#selfie-with-id)
* [Video call](#video-call)
* [Phone number verification](#phone-number)
* [Email verification](#email)
* [Geolocation](#geolocation)
* [User questionnaire](#user-questionnaire)
* [Operator 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`&#x20;

<table data-full-width="true"><thead><tr><th width="259">Flag</th><th width="448">Description</th><th width="97.51171875">Default</th><th width="127.421875">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>

***

### 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:**&#x20;
  * disable\_document\_capture&#x20;
  * allow\_document\_upload&#x20;
  * document\_types&#x20;
  * document\_countries

<table data-full-width="true"><thead><tr><th width="234.47265625">Flag</th><th width="448">Description</th><th width="119.3828125">Default</th><th width="149.3515625">Type</th></tr></thead><tbody><tr><td><code>disable_document_capture</code></td><td>Disables live document scanning. Users can only upload images of their documents.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>allow_document_upload</code></td><td>Enables the option to either scan or upload the document.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>allow_nfc_capture</code><br><br></td><td>Enables NFC chip reading for supported identity documents (e.g. biometric passports and IDs).<br>When enabled, users can scan the document’s NFC chip using a compatible device.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>document_types</code></td><td><p>A list of allowed document types.<br></p><p>Possible values:</p><pre data-overflow="wrap"><code>"id", "passport", "driver_license", "residence_license"
</code></pre></td><td>All types</td><td>Array&#x3C;string></td></tr><tr><td><code>document_countries</code></td><td>Restricts accepted document issuers to specific country codes. (e.g., <code>"USA", "DEU", "ITA"</code>)</td><td>Unrestricted</td><td>Array&#x3C;string></td></tr><tr><td><code>optional_continue_on_another_device</code></td><td>Allows users to optionally switch to another device to continue the session.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr></tbody></table>

#### **cURL example:**

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

<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": {
                "es": "ID verification"
                ,
            "type": "identity-document",
            "key": "select_document_id",
            "flags": {
                "allow_document_upload": true,
                "document_types": [
                    "id",
                    "passport",
                    "driver_license",
                    "residence_license"
                ]
            }
        }
    ]
}'
```

</details>

***

### **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:**&#x20;
  * liveness
  * allow\_face\_upload
  * adaptive\_liveness
  * instructions

<table data-full-width="true"><thead><tr><th width="215.96484375">Flag</th><th width="466.70703125">Description</th><th width="158.09765625">Default</th><th width="149.48046875">Type</th></tr></thead><tbody><tr><td><code>liveness</code></td><td><p>Defines the type of liveness check:</p><ul><li><code>true</code>: active liveness</li><li> <code>false</code>: passive liveness</li></ul></td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>allow_face_upload</code></td><td><p>Allows the user to upload a selfie instead of using the camera.</p><p><br>⚠️ <em>This flag is ignored if <code>liveness</code> is <code>true</code>, as active checks require live input.</em></p></td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>optional_continue_on_another_device</code></td><td>Allows users to optionally switch to another device to continue the session.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>adaptive_liveness</code></td><td>(SDKs only) Enables the new <strong>Adaptive Liveness</strong> experience with improved UI and detection. Must be <code>true</code> to use Adaptive Liveness.<br>⚠️ If <code>adaptive_liveness</code> is <code>true</code>, the <code>liveness</code> flag <strong>must</strong> be <code>false</code>.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>instructions</code></td><td>Defines the actions the user must perform for Adaptive Liveness. <br>Only applicable if <code>adaptive_liveness</code> is <code>true</code>.<br>Currently supported option: <code>[ "smile" ]</code>.<br></td><td><code>[ "smile" ]</code></td><td>&#x3C;array&#x3C;string></td></tr></tbody></table>

#### **cURL example:**

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

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

</details>

***

### 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:**&#x20;
  * general\_document\_types

<table data-full-width="true"><thead><tr><th width="224.64453125">Flag</th><th width="431.55859375">Description</th><th width="172">Default</th><th width="121">Type</th></tr></thead><tbody><tr><td><code>general_document_types</code></td><td><p>A list of allowed document types.<br>If omitted or set to an empty array, all document types will be available for upload.</p><p></p><p>Possible values:</p><pre data-overflow="wrap"><code>"bank_statement", "utility_bill", "yellow_slip", "drivers_license", "vehicle_registration_certificate"
</code></pre></td><td>All types</td><td>&#x3C;array></td></tr></tbody></table>

#### **cURL example:**

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

<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": {
        "optional_continue_on_another_device": true,
        "language": "en"
},
"steps": [
    {
        "title": {
            "en": "Liveness check"
            },
        "type": "liveness",
        "key": "liveness",
        "flags": {
            "liveness": true
        }
    },
    {
        "title": {
            "en": "Proof of address"
            },
        "type": "general-document",
        "key": "select_general_document",
        "flags": {
            "general_document_types": [
                "bank_statement",
                "utility_bill",
                "yellow_slip",
                "drivers_license",
                "vehicle_registration_certificate"
            ]
        }
    }
]
}'
```

</details>

***

### 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:**&#x20;
  * allow\_face\_doc\_upload
  * require\_face\_document

<table data-full-width="true"><thead><tr><th width="209.796875">Flag</th><th width="391.66796875">Description</th><th width="172">Default</th><th width="121">Type</th></tr></thead><tbody><tr><td><code>allow_face_doc_upload</code></td><td>Allows users to upload an image of themselves holding the document.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>require_face_document</code></td><td>Requires users to capture themselves holding the document live.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>optional_continue_on_another_device</code></td><td>Allows users to optionally switch to another device to continue the session.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr></tbody></table>

#### **cURL example:**

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

<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": {
        "restrict_url_sharing": true,
        "language": "en"
},
"steps": [
    {
        "title": {
            "en": "Selfie with ID"
            },
        "type": "face-document",
        "key": "capture_face_document",
        "flags": {
            "allow_face_doc_upload": true,
            "require_face_document": true
        }
    }
]
}'
```

</details>

***

### 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)*

<table data-full-width="true"><thead><tr><th width="211.5390625">Flag</th><th width="448">Description</th><th width="172">Default</th><th width="121" valign="middle">Type</th></tr></thead><tbody><tr><td><code>steps</code></td><td>List of steps to run during the video call (except <code>language</code> and <code>operator_questionnaire</code>).</td><td><code>[ ]</code></td><td valign="middle">&#x3C;array></td></tr><tr><td><code>resetSteps</code></td><td>If true, user verification data resets when they rejoin the call. </td><td><code>false</code></td><td valign="middle">&#x3C;boolean></td></tr><tr><td><code>hideCameraOption</code></td><td>Enabling this will hide the camera icon, preventing users from turning off the camera.</td><td><code>false</code></td><td valign="middle">&#x3C;boolean></td></tr><tr><td><code>nameRequired</code></td><td>Requires users to enter their name before joining.</td><td><code>false</code></td><td valign="middle">&#x3C;boolean></td></tr><tr><td><code>multiple_participants</code></td><td>Enables multi-user video sessions.</td><td><code>false</code></td><td valign="middle">&#x3C;boolean></td></tr></tbody></table>

#### **cURL example:**

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

<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": [
    {
            "type": "video-call",
            "title": {
                "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"
                        ]
                    }
                }
            ]
        }
]
}'
```

</details>

***

### 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.&#x20;
* **Collection** of the user's phone number.&#x20;

**Phone number step configurations:**

* **Type**: `phone-number`
* **Key**: `phone_number`
* **Flags:**&#x20;
  * require\_phone\_number\_check
  * require\_phone\_number

<table data-full-width="true"><thead><tr><th width="252.58984375">Flag</th><th width="391.9375">Description</th><th width="172">Default</th><th width="121">Type</th></tr></thead><tbody><tr><td><code>require_phone_number_check</code></td><td>Requires users to verify their number via an OTP code.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>require_phone_number</code></td><td>Requires users to submit a phone number without verification.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr></tbody></table>

#### **cURL example:**

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

<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": "it"
},
"steps": [
    {
        "title": {
            "it": "Phone number verification"
            },
        "type": "phone-number",
        "key": "phone_number",
        "flags": {
            "require_phone_number_check": true
        }
    }
]
}'
```

</details>

***

### 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.&#x20;
* **Collection** of the user's email.

**Email step configurations:**

* **Type**: `email`
* **Key**: `require_email`
* **Flags:**
  * require\_email\_check
  * require\_email

<table data-full-width="true"><thead><tr><th width="215">Flag</th><th width="360">Description</th><th width="112">Default</th><th width="121">Type</th></tr></thead><tbody><tr><td><code>require_email_check</code></td><td>Requires email verification via an OTP code.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>require_email</code></td><td>Requires users to submit an email without verification.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr></tbody></table>

#### **cURL example:**

Example using cURL with **`return_url`** & **`language`** flags and  **`email`** step:

<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": [
    {
        "title": {
            "en": "Email verification"
            },
        "type": "email",
        "key": "require_email",
        "flags": {
            "require_email_check": true
        }
    }
]
}'
```

</details>

***

### Geolocation

The Geolocation step requests the user’s location data by prompting for browser permission.

**Geolocation step configurations:**

* **Type**: `geolocation`
* **Key**: `require_geolocation`
* **Flags:**&#x20;
  * require\_geolocation

<table data-full-width="true"><thead><tr><th width="280">Flag</th><th width="448">Description</th><th width="172">Default</th><th width="121">Type</th></tr></thead><tbody><tr><td><code>require_geolocation</code></td><td>Requires location access to proceed through the step.</td><td><code>true</code></td><td>&#x3C;boolean></td></tr></tbody></table>

#### **cURL example:**

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

<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": [
    {
        "title": {
            "en": "Geolocation"
            },
        "type": "geolocation",
        "key": "require_geolocation",
        "flags": {
            "require_geolocation": true
        }
    }
]
}'
```

</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 answer
  * `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>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>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;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,
        "format": {
            "email"
            },
        "answer": {
            "en": "This is a prefilled answer",
            "es": "Esta es una respuesta prellenada."
        },
        "showConditions": {
            "questionKey": "question1",
            "answer": "option1"
        },
        "readOnly": false
    }
]
```

</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-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 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>

***

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

```json
"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`: **Short answer** – Operator types a short answer as plain text.
  * `multiple-choice`: **Checkbox** – 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` – Short answer
  * `multiple-choice` – Checkbox
  * `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:

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

#### **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.

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

<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": "document-collection"
</code></pre></td></tr><tr><td><code>title</code></td><td>The title of the operator questionnaire, displayed as the tab name in the session. The title can be an <code>&#x3C;object></code> containing different <strong>languages</strong>, allowing the title to be displayed in the selected language.</td><td>-</td><td>&#x3C;string> or &#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>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.</td><td>-</td><td>&#x3C;string> or &#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> and <code>options</code>.</td><td>-</td><td>&#x3C;array></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">"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"
        }
    ]
    }
]
</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></tbody></table>

#### **cURL example:**

<details>

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

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

</details>

***

## 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.

<table data-full-width="true"><thead><tr><th width="218">Parameter name</th><th width="437">Description</th><th width="216">Default</th><th width="121">Type</th></tr></thead><tbody><tr><td><code>name</code></td><td>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).</td><td>null</td><td>&#x3C;string></td></tr><tr><td><code>clientUserId</code></td><td>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.</td><td>null</td><td>&#x3C;string></td></tr><tr><td><code>groupId</code></td><td>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.</td><td>null</td><td>&#x3C;string></td></tr><tr><td><code>scheduleStartTime</code></td><td>The datetime when the session becomes available to the end-user. Before this time, the session cannot be started.<br>Format: ISO 8601 — e.g., <code>"2024-06-20T07:33:00.000Z"</code></td><td>null</td><td>&#x3C;string> (ISO 8601 datetime)</td></tr><tr><td><code>scheduleEndTime</code></td><td>The datetime after which the session is no longer accessible to the end-user.<br>Format: ISO 8601 — e.g., <code>"2024-06-20T09:00:00.000Z"</code></td><td>null</td><td>&#x3C;string> (ISO 8601 datetime)</td></tr></tbody></table>

**Example:**

```json
{
  "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": [...]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.identomat.com/developer-tools/developer-guide/kyc-know-your-customer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.