> For the complete documentation index, see [llms.txt](https://docs.identomat.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.identomat.com/identomat-documentation-ukr/posibnik-dlya-rozrobnikiv/kyc-know-your-customer.md).

# KYC (Know Your Customer)

Кожен потік верифікації KYC складається з настроюваних кроків, які визначають, як перевіряється особа кінцевого користувача. Прапорці та кроки, перелічені нижче, визначають, які перевірки включені в процес та як вони виконуються.

## Flags (Прапорці)

Параметр `flags` — це об'єкт із необов'язковими прапорцями конфігурації, які налаштовують потік верифікації KYC. Нижче наведено огляд найпоширеніших прапорців:

<table data-full-width="true"><thead><tr><th width="218">Назва прапорця</th><th width="437">Опис</th><th width="216">За замовчуванням</th><th width="121">Тип</th></tr></thead><tbody><tr><td><code>skip_face</code></td><td>Пропускає крок <code>liveness</code>, якщо він вже існує у визначених кроках. Запобігає дублюванню при використанні власних потоків.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>skip_document</code></td><td>Пропускає крок <code>identity-document</code>, якщо він вже існує у визначених кроках. Запобігає дублюванню при використанні власних потоків.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>return_url</code></td><td>URL для перенаправлення користувача після завершення процесу ідентифікації. Якщо не вказано, вважається, що сесія вбудована в iframe.</td><td><code>null</code></td><td>&#x3C;string></td></tr><tr><td><code>language</code></td><td><p>Код мови інтерфейсу користувача. Підтримувані значення:</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></td><td><code>"en"</code></td><td>&#x3C;string></td></tr><tr><td><code>skip_desktop</code></td><td>Обмежує сесії лише мобільними пристроями. Якщо ініційовано на комп'ютері, показується QR-код для перенесення сесії на мобільний пристрій.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>switch_device_url</code></td><td>Користувацький URL для відображення в QR-коді, коли камера недоступна або заблокована. Якщо не вказано або порожньо, QR-код не відображатиметься.</td><td><code>null</code></td><td>&#x3C;string></td></tr><tr><td><code>restrict_url_sharing</code></td><td>Забороняє використання URL сесії на іншому браузері чи пристрої.<br>Якщо <code>true</code>, QR-код не з'явиться, коли доступ до камери заборонено — якщо тільки <code>switch_device_url</code> також не визначено.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>requiredHdMedia</code></td><td>Вимагає використання камери Full HD (1080p+) для кроків <code>liveness</code> та <code>identity-document</code>. Якщо не виконано, показується QR-код для переходу користувача на інший пристрій.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr></tbody></table>

## Steps (Кроки)

Масив `steps` визначає послідовність та структуру процесу ідентифікації. Він включається разом із параметрами `company_key` та `flags` при створенні сесії.

Кожен крок у масиві `steps` може містити такі властивості:

<table><thead><tr><th width="163.91015625">Властивість</th><th>Опис</th></tr></thead><tbody><tr><td><code>type</code></td><td>Тип конкретного кроку (див. список підтримуваних типів кроків нижче).</td></tr><tr><td><code>key</code></td><td>Унікальний ідентифікатор кроку. Цей ключ можна налаштувати, але він має залишатися унікальним у межах сесії.</td></tr><tr><td><code>flags</code></td><td>Прапорці конфігурації, специфічні для кроку, які контролюють поведінку цього кроку.</td></tr><tr><td><code>title</code></td><td>Користувацький заголовок, наданий клієнтом, що відображається користувачеві під час цього кроку в інтерфейсі.</td></tr></tbody></table>

### **Підтримувані типи кроків**

Нижче наведено список усіх типів кроків, наразі підтримуваних системою:

* [Language (Мова)](#language-mova)
* [ID verification (Верифікація документа)](#identity-document-verification-verifikaciya-dokumenta-sho-posvidchuye-osobu)
* [Liveness check (Перевірка живості)](#liveness-check-perevirka-zhivosti)
* [Proof of Address (Підтвердження адреси)](#proof-of-address-pidtverdzhennya-adresi)
* [Selfie with ID (Селфі з документом)](#selfie-with-id-selfi-z-dokumentom)
* [Video call (Відеодзвінок)](#video-call-videodzvinok)
* [Phone number verification (Верифікація номера телефону)](#phone-number-nomer-telefonu)
* [Email verification (Верифікація email)](#email)
* [Geolocation (Геолокація)](#geolocation-geolokaciya)
* [AnyDoc reader ](#anydoc-reader)
* [SSN verification (Перевірка SSN)](#ssn-verification-perevirka-ssn)
* [User questionnaire (Опитувальник користувача)](#user-questionnaire-opituvalnik-koristuvacha)
* [Operator questionnaire (Опитувальник оператора)](#operator-questionnaire-opituvalnik-operatora)

***

### Language (Мова)

Крок **Language** дозволяє користувачеві обрати бажану мову інтерфейсу на початку процесу ідентифікації.

**Конфігурації кроку Language:**

* **Заголовок:** `Language`
* **Тип**: `language`
* **Ключ**: `language`
* **Масив** `languages`

<table data-full-width="true"><thead><tr><th width="136.875">Прапорець</th><th width="409.54296875">Опис</th><th width="173.984375">За замовчуванням</th><th width="131.734375">Тип</th></tr></thead><tbody><tr><td><code>languages</code></td><td><p>Масив кодів мов для відображення. Якщо залишити порожнім, показуються всі підтримувані мови.</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>Усі</td><td>Array&#x3C;string></td></tr></tbody></table>

<details>

<summary><em>Розгорнути, щоб переглянути приклад</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 (Верифікація документа, що посвідчує особу)

Крок Identity Document передбачає, що користувачі сканують або завантажують фото своїх документів, що посвідчують особу.

**Конфігурації кроку Identity document:**

* **Заголовок:** `ID verification`
* **Тип**: `identity-document`
* **Ключ**: `identity-document`
* **Прапорці:**
  * disable\_document\_capture
  * allow\_document\_upload
  * document\_types
  * document\_countries

<table data-full-width="true"><thead><tr><th width="234.47265625">Прапорець</th><th width="419.66796875">Опис</th><th width="155.9609375">За замовчуванням</th><th width="149.3515625">Тип</th></tr></thead><tbody><tr><td><code>disable_document_capture</code></td><td>Вимикає живе сканування документа. Користувачі можуть лише завантажувати зображення своїх документів.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>allow_document_upload</code></td><td>Вмикає опцію сканувати або завантажувати документ.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>allow_nfc_capture</code><br><br></td><td>Вмикає зчитування NFC-чипа для підтримуваних документів, що посвідчують особу (наприклад, біометричні паспорти та ID-картки).<br>Коли увімкнено, користувачі можуть сканувати NFC-чип документа за допомогою сумісного пристрою.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>document_types</code></td><td><p>Список дозволених типів документів.<br></p><p>Можливі значення:</p><pre data-overflow="wrap"><code>"id", "passport", "driver_license", "residence_license"
</code></pre></td><td>Усі типи</td><td>Array&#x3C;string></td></tr><tr><td><code>document_countries</code></td><td>Обмежує прийнятних видавців документів конкретними кодами країн (наприклад, <code>"USA", "DEU", "ITA"</code>).</td><td>Без обмежень</td><td>Array&#x3C;string></td></tr><tr><td><code>optional_continue_on_another_device</code></td><td>Дозволяє користувачам за бажанням перейти на інший пристрій, щоб продовжити сесію.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr></tbody></table>

**Приклад cURL:**

Приклад використання cURL із прапорцями **`return_url`** та **`language`** та кроком верифікації **`identity-document`**:

<details>

<summary><em>Розгорнути, щоб переглянути приклад</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>

**Перевірка даних документа (Document data review)**

Коли увімкнено, користувачам показується сторінка перегляду після сканування документа, де вони можуть перевірити та виправити витягнуті дані перед подачею.

Щоб увімкнути перевірку даних документа, додайте об'єкт `review` до конфігурації кроку:

<table><thead><tr><th width="139.65234375">Прапорець</th><th width="352.6171875">Опис</th><th width="157.6640625">За замовчуванням</th><th width="158.55078125">Тип</th></tr></thead><tbody><tr><td><code>check</code></td><td>Вмикає сторінку перевірки даних документа.</td><td><code>false</code></td><td><code>&#x3C;boolean></code></td></tr><tr><td><code>allowedUsers</code></td><td>Визначає, хто може редагувати витягнуті дані на сторінці перегляду.<br>Можливі значення: <code>"client"</code> (кінцевий користувач, що проходить верифікацію), <code>"operator"</code> (оператор, який контролює сесію).</td><td>—</td><td><code>Array&#x3C;string></code></td></tr><tr><td><code>fields</code></td><td>Карта OCR-полів для включення на сторінку перегляду. Кожне поле можна налаштувати властивостями <code>editable</code> та <code>mandatory</code>.</td><td>—</td><td><code>Object</code></td></tr></tbody></table>

**Властивості конфігурації поля:**

<table><thead><tr><th width="120.27734375">Прапорець</th><th width="461.484375">Опис</th><th>Тип</th></tr></thead><tbody><tr><td><code>type</code></td><td>Тип даних поля. Можливі значення: <code>"string"</code>, <code>"datestring"</code></td><td><code>&#x3C;string></code></td></tr><tr><td><code>editable</code></td><td>Чи може користувач або оператор редагувати це поле.</td><td><code>&#x3C;boolean></code></td></tr><tr><td><code>mandatory</code></td><td>Чи має поле бути заповненим перед подачею.</td><td><code>&#x3C;boolean></code></td></tr></tbody></table>

**Настроювані поля:**

| Поле                         | Ключ                   | Компонент        |
| ---------------------------- | ---------------------- | ---------------- |
| Ім'я (англ.)                 | `firstNameEn`          | Текстове поле    |
| Ім'я (місцевою мовою)        | `firstNameLocal`       | Текстове поле    |
| По батькові (англ.)          | `middleNameEn`         | Текстове поле    |
| По батькові (місцевою мовою) | `middleNameLocal`      | Текстове поле    |
| Прізвище (англ.)             | `lastNameEn`           | Текстове поле    |
| Прізвище (місцевою мовою)    | `lastNameLocal`        | Текстове поле    |
| Ім'я батька (англ.)          | `fatherNameEn`         | Текстове поле    |
| Ім'я батька (місцевою мовою) | `fatherNameLocal`      | Текстове поле    |
| Дата народження              | `dateOfBirth`          | Вибір дати       |
| Місце народження             | `placeOfBirth`         | Текстове поле    |
| Стать                        | `sex`                  | Перемикач        |
| Громадянство                 | `citizenship`          | Список країн     |
| Національність               | `nationality`          | Список країн     |
| Номер документа              | `documentNumber`       | Текстове поле    |
| Орган видачі                 | `authority`            | Текстове поле    |
| Термін дії документа         | `documentExpireDate`   | Вибір дати       |
| Дата видачі документа        | `documentIssuingDate`  | Вибір дати       |
| Країна видачі документа      | `documentIssuingState` | Список країн     |
| Особистий номер              | `personalNumber`       | Текстове поле    |
| Адреса                       | `address`              | Текстова область |
| Область/штат                 | `state`                | Текстове поле    |

**Ієрархія довіри джерела**

Поля, заповнені з довіреного джерела, є постійно **лише для читання**, незалежно від конфігурації `editable`. Це правило застосовується на рівні бекенду і не може бути перевизначене.

Наступні джерела створюють поля, недоступні для редагування:

* `NFC`
* `MRZ`
* `QR`

**Приклад конфігурації:**

<details>

<summary><em>Розгорнути, щоб переглянути приклад</em></summary>

```bash
{
  "type": "identity-document",
  "key": "select_document_id",
  "title": { "en": "ID verification" },
  "flags": {
    "document_types": ["id", "passport", "driver_license", "residence_license"],
    "allow_document_upload": true,
    "disable_document_capture": false
  },
  "review": {
    "check": true,
    "allowedUsers": ["client", "operator"],
    "fields": {
      "firstNameEn":          { "type": "string",     "editable": true, "mandatory": true },
      "firstNameLocal":       { "type": "string",     "editable": true, "mandatory": true },
      "middleNameEn":         { "type": "string",     "editable": true, "mandatory": true },
      "middleNameLocal":      { "type": "string",     "editable": true, "mandatory": true },
      "lastNameEn":           { "type": "string",     "editable": true, "mandatory": true },
      "lastNameLocal":        { "type": "string",     "editable": true, "mandatory": true },
      "fatherNameEn":         { "type": "string",     "editable": true, "mandatory": true },
      "fatherNameLocal":      { "type": "string",     "editable": true, "mandatory": true },
      "dateOfBirth":          { "type": "datestring", "editable": true, "mandatory": true },
      "placeOfBirth":         { "type": "string",     "editable": true, "mandatory": true },
      "sex":                  { "type": "string",     "editable": true, "mandatory": true },
      "citizenship":          { "type": "string",     "editable": true, "mandatory": true },
      "nationality":          { "type": "string",     "editable": true, "mandatory": true },
      "documentNumber":       { "type": "string",     "editable": true, "mandatory": true },
      "authority":            { "type": "string",     "editable": true, "mandatory": true },
      "documentExpireDate":   { "type": "datestring", "editable": true, "mandatory": true },
      "documentIssuingDate":  { "type": "datestring", "editable": true, "mandatory": true },
      "documentIssuingState": { "type": "string",     "editable": true, "mandatory": true },
      "personalNumber":       { "type": "string",     "editable": true, "mandatory": true },
      "address":              { "type": "string",     "editable": true, "mandatory": true },
      "state":                { "type": "string",     "editable": true, "mandatory": true }
    }
  }
}
```

</details>

***

### **Liveness check (Перевірка живості)**

Крок **Liveness** перевіряє, чи фізично присутній користувач, аналізуючи живе зображення обличчя або відео.

Identomat підтримує два типи перевірки живості:

* **Пасивна (Passive liveness):** Користувач вирівнює обличчя в межах овальної рамки, поки система знімає коротке (приблизно 2-секундне) відео.
* **Активна (Active liveness):** Користувач виконує конкретні дії, щоб підтвердити свою присутність як живої людини.

**Конфігурації кроку Liveness check:**

* **Заголовок:** `Liveness`
* **Тип**: `liveness`
* **Ключ**: `liveness`
* **Прапорці:**
  * liveness
  * allow\_face\_upload
  * adaptive\_liveness
  * instructions

<table data-full-width="true"><thead><tr><th width="215.96484375">Прапорець</th><th width="466.70703125">Опис</th><th width="158.09765625">За замовчуванням</th><th width="149.48046875">Тип</th></tr></thead><tbody><tr><td><code>liveness</code></td><td><p>Визначає тип перевірки живості:</p><ul><li><code>true</code>: активна живість</li><li><code>false</code>: пасивна живість</li></ul></td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>allow_face_upload</code></td><td><p>Дозволяє користувачеві завантажити селфі замість використання камери.</p><p><br>⚠️ <em>Цей прапорець ігнорується, якщо <code>liveness</code> дорівнює <code>true</code>, оскільки активні перевірки вимагають живого вводу.</em></p></td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>optional_continue_on_another_device</code></td><td>Дозволяє користувачам за бажанням перейти на інший пристрій, щоб продовжити сесію.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>adaptive_liveness</code></td><td>(Лише SDK) Вмикає новий досвід <strong>Adaptive liveness</strong> із покращеним UI та виявленням. Має бути <code>true</code>, щоб використовувати Adaptive Liveness.<br>⚠️ Якщо <code>adaptive_liveness</code> дорівнює <code>true</code>, прапорець <code>liveness</code> <strong>має</strong> бути <code>false</code>.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>instructions</code></td><td>Визначає дії, які користувач має виконати для Adaptive Liveness.<br>Застосовується лише якщо <code>adaptive_liveness</code> дорівнює <code>true</code>.<br>Наразі підтримувана опція: <code>[ "smile" ]</code>.<br></td><td><code>[ "smile" ]</code></td><td>Array&#x3C;string></td></tr></tbody></table>

**Приклад cURL:**

Приклад використання cURL із прапорцями **`document_countries`** та **`language`** та кроками верифікації **`identity-document`** і *активної* **`liveness`**:

<details>

<summary><em>Розгорнути, щоб переглянути приклад</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 (Підтвердження адреси)

Крок POA включає верифікацію Proof of Address та аналіз інших типів документів. Цей крок підтримує широкий спектр загальних типів документів, таких як рахунки за комунальні послуги чи банківські виписки.

**Конфігурації кроку Proof of Address:**

* **Заголовок:** `Proof of Address`
* **Тип**: `general-document`
* **Ключ**: `select_general_document`
* **Прапорці:**
  * general\_document\_types

<table data-full-width="true"><thead><tr><th width="224.64453125">Прапорець</th><th width="431.55859375">Опис</th><th width="172">За замовчуванням</th><th width="121">Тип</th></tr></thead><tbody><tr><td><code>general_document_types</code></td><td><p>Список дозволених типів документів.<br>Якщо не вказано або встановлено порожній масив, для завантаження будуть доступні всі типи документів.</p><p>Можливі значення:</p><pre data-overflow="wrap"><code>"bank_statement", "utility_bill", "yellow_slip", "drivers_license", "vehicle_registration_certificate"
</code></pre></td><td>Усі типи</td><td>&#x3C;array></td></tr></tbody></table>

**Приклад cURL:**

Приклад використання cURL із прапорцями **`optional_continue_on_another_device`** та **`language`** та кроками **`liveness`** і **`general-document`**:

<details>

<summary><em>Розгорнути, щоб переглянути приклад</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 (Селфі з документом)

У кроці Selfie with ID користувачам потрібно тримати документ у руках так, щоб було видно і обличчя, і документ.

**Конфігурації кроку Selfie with ID:**

* **Заголовок:** `Selfie with ID`
* **Тип**: `face-document`
* **Ключ**: `capture_face_document`
* **Прапорці:**
  * allow\_face\_doc\_upload
  * require\_face\_document

<table data-full-width="true"><thead><tr><th width="209.796875">Прапорець</th><th width="391.66796875">Опис</th><th width="172">За замовчуванням</th><th width="121">Тип</th></tr></thead><tbody><tr><td><code>allow_face_doc_upload</code></td><td>Дозволяє користувачам завантажити зображення себе з документом.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>require_face_document</code></td><td>Вимагає, щоб користувачі зробили живий знімок себе з документом.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>optional_continue_on_another_device</code></td><td>Дозволяє користувачам за бажанням перейти на інший пристрій, щоб продовжити сесію.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr></tbody></table>

**Приклад cURL:**

Приклад використання cURL із прапорцями **`restrict_url_sharing`** та **`language`** та кроком **`face-document`**:

<details>

<summary><em>Розгорнути, щоб переглянути приклад</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 (Відеодзвінок)

У кроці Video call користувач з'єднується з оператором для живої верифікації. Це може включати будь-який із кроків верифікації Identomat.

Identomat пропонує два режими дзвінків:

* **Один на один:** Передбачає безпечний відеодзвінок між клієнтом та оператором верифікації
* **Багатокористувацький дзвінок:** Дозволяє верифікацію декількох клієнтів у межах однієї сесії. Кожен користувач може проходити свій власний налаштований робочий процес, адаптований до конкретного бізнес-процесу.

**Конфігурації кроку Video call:**

* **Заголовок:** `Video call`
* **Тип**: `video-call`
* **Ключ**: `video-call`
* **Масив** `steps`
* **resetSteps**: `true/false` *(необов'язково)*
* **hideCameraOption**: `true/false` *(необов'язково)*
* **nameRequired**\*:\* `true/false` *(необов'язково)*
* **multiple\_participants:** `true/false` *(необов'язково)*

<table data-full-width="true"><thead><tr><th width="211.5390625">Прапорець</th><th width="448">Опис</th><th width="172">За замовчуванням</th><th width="121" valign="middle">Тип</th></tr></thead><tbody><tr><td><code>steps</code></td><td>Список кроків для виконання під час відеодзвінка (крім <code>language</code> та <code>operator_questionnaire</code>).</td><td><code>[ ]</code></td><td valign="middle">&#x3C;array></td></tr><tr><td><code>resetSteps</code></td><td>Якщо true, дані верифікації користувача скидаються, коли він повторно приєднується до дзвінка.</td><td><code>false</code></td><td valign="middle">&#x3C;boolean></td></tr><tr><td><code>hideCameraOption</code></td><td>Увімкнення цього приховає іконку камери, забороняючи користувачам вимикати камеру.</td><td><code>false</code></td><td valign="middle">&#x3C;boolean></td></tr><tr><td><code>nameRequired</code></td><td>Вимагає, щоб користувачі ввели своє ім'я перед приєднанням.</td><td><code>false</code></td><td valign="middle">&#x3C;boolean></td></tr><tr><td><code>multiple_participants</code></td><td>Вмикає багатокористувацькі відеосесії.</td><td><code>false</code></td><td valign="middle">&#x3C;boolean></td></tr></tbody></table>

**Приклад cURL:**

Приклад використання cURL із прапорцями **`return_url`** та **`language`** та кроком **`video-call`** із кроком **`identity-document`**:

<details>

<summary><em>Розгорнути, щоб переглянути приклад</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 може включати:

* **Верифікацію** номера телефону користувача за допомогою коду OTP.
* **Збір** номера телефону користувача.

**Конфігурації кроку Phone number:**

* **Тип**: `phone-number`
* **Ключ**: `phone_number`
* **Прапорці:**
  * require\_phone\_number\_check
  * require\_phone\_number

<table data-full-width="true"><thead><tr><th width="252.58984375">Прапорець</th><th width="391.9375">Опис</th><th width="172">За замовчуванням</th><th width="121">Тип</th></tr></thead><tbody><tr><td><code>require_phone_number_check</code></td><td>Вимагає, щоб користувачі перевірили свій номер за допомогою коду OTP.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>require_phone_number</code></td><td>Вимагає, щоб користувачі надали номер телефону без перевірки.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr></tbody></table>

**Приклад cURL:**

Приклад використання cURL із прапорцями **`return_url`** та **`language`** та кроком **`phone-number`**:

<details>

<summary><em>Розгорнути, щоб переглянути приклад</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

Крок Email дозволяє користувачам перевіряти або надавати свою адресу електронної пошти.

Крок Email може включати:

* **Верифікацію** email користувача за допомогою коду OTP.
* **Збір** email користувача.

**Конфігурації кроку Email:**

* **Тип**: `email`
* **Ключ**: `require_email`
* **Прапорці:**
  * require\_email\_check
  * require\_email

<table data-full-width="true"><thead><tr><th width="215">Прапорець</th><th width="360">Опис</th><th width="112">За замовчуванням</th><th width="121">Тип</th></tr></thead><tbody><tr><td><code>require_email_check</code></td><td>Вимагає верифікації email за допомогою коду OTP.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>require_email</code></td><td>Вимагає, щоб користувачі надали email без перевірки.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr></tbody></table>

**Приклад cURL:**

Приклад використання cURL із прапорцями **`return_url`** та **`language`** та кроком **`email`**:

<details>

<summary><em>Розгорнути, щоб переглянути приклад</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 (Геолокація)

Крок Geolocation запитує дані про місцезнаходження користувача, запитуючи дозвіл браузера.

**Конфігурації кроку Geolocation:**

* **Тип**: `geolocation`
* **Ключ**: `require_geolocation`
* **Прапорці:**
  * require\_geolocation

<table data-full-width="true"><thead><tr><th width="280">Прапорець</th><th width="448">Опис</th><th width="172">За замовчуванням</th><th width="121">Тип</th></tr></thead><tbody><tr><td><code>require_geolocation</code></td><td>Вимагає доступу до місцезнаходження для проходження кроку.</td><td><code>true</code></td><td>&#x3C;boolean></td></tr></tbody></table>

**Приклад cURL:**

Приклад використання cURL із прапорцями **`return_url`** та **`language`** та кроком **`geolocation`**:

<details>

<summary><em>Розгорнути, щоб переглянути приклад</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>

***

### **AnyDoc reader**

Крок AnyDoc дозволяє витягувати структуровані дані **з документів будь-якого типу** за допомогою ШІ — таких як розрахункові листки, банківські виписки, рахунки за комунальні послуги чи податкові довідки. Ви визначаєте поля, які потрібно витягнути, а система автоматично зчитує та перевіряє їх.

**Конфігурації кроку AnyDoc:**

* **Заголовок:** `AnyDoc upload`
* **Тип**: `anydoc-reader`
* **Ключ**: визначається клієнтом, має залишатися унікальним у межах сесії
* **Параметри:**
  * `documentType`
  * `allowedFormats`
  * `pageConfiguration`
  * `pageCount`
  * `documentValidity`
  * `language`
  * `extractionHint`
  * `confidenceThreshold`
  * `retryLimit`
  * `fields`

<table><thead><tr><th width="174.453125">Параметр</th><th width="434.16015625">Опис</th><th width="199.34375">За замовчуванням</th><th>Тип</th></tr></thead><tbody><tr><td><code>documentType</code></td><td>Довільна текстова мітка, що ідентифікує тип документа (наприклад, «Payslip», «Bank Statement»). Використовується внутрішньо в деталях сесії та виводі API. Обов'язково.</td><td>-</td><td>&#x3C;string></td></tr><tr><td><code>allowedFormats</code></td><td>Формати файлів, прийняті для завантаження. Можливі значення: <code>"pdf"</code>, <code>"image"</code></td><td>Усі типи</td><td>Array&#x3C;string></td></tr><tr><td><code>pageConfiguration</code></td><td>Чи очікується, що документ буде однією чи декількома сторінками. Можливі значення: <code>"single"</code>, <code>"multiple"</code></td><td><code>"single"</code></td><td>&#x3C;string></td></tr><tr><td><code>pageCount</code></td><td>Очікувана кількість сторінок, використовується лише коли <code>pageConfiguration</code> дорівнює <code>"multiple"</code>. Якщо не вказано, обробляються всі завантажені сторінки.</td><td>null</td><td>&#x3C;number></td></tr><tr><td><code>documentValidity</code></td><td>Встановлює максимальний вік документа на основі поля дати, витягнутого з документа. Див. деталі нижче.</td><td><code>{ "enabled": false }</code></td><td>&#x3C;object></td></tr><tr><td><code>language</code></td><td>Очікувана мова документа, використовується для покращення точності витягування. Якщо не вказано, мова визначається автоматично.</td><td>Автовизначення</td><td>&#x3C;string></td></tr><tr><td><code>extractionHint</code></td><td>Додатковий контекст про документ загалом, наданий ШІ разом із підказками на рівні полів. Рекомендується англійською мовою незалежно від мови документа.</td><td>null</td><td>&#x3C;string></td></tr><tr><td><code>confidenceThreshold</code></td><td>Мінімальний бал достовірності (0–100), необхідний для прийняття витягнутого поля без позначення. Застосовується до всіх полів, якщо не перевизначено для окремого поля.</td><td><code>80</code></td><td>&#x3C;number></td></tr><tr><td><code>retryLimit</code></td><td>Максимальна кількість разів, коли користувач може завантажити чи зняти документ на цьому кроці.</td><td><code>3</code></td><td>&#x3C;number></td></tr><tr><td><code>fields</code></td><td>Масив об'єктів полів, що визначають дані для витягування. Див. деталі нижче.</td><td>-</td><td>Array&#x3C;object></td></tr></tbody></table>

**Об'єкт `documentValidity`:**

<table><thead><tr><th width="128.01953125">Властивість</th><th width="535.7109375">Опис</th><th width="140.33984375">За замовчуванням</th><th>Тип</th></tr></thead><tbody><tr><td><code>enabled</code></td><td>Вмикає або вимикає перевірку чинності.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>dateField</code></td><td><code>key</code> поля (має бути типу <code>date</code>), витягнуте значення якого перевіряється проти <code>maxAge</code>. Обов'язково, коли <code>enabled</code> дорівнює <code>true</code>.</td><td>-</td><td>&#x3C;string></td></tr><tr><td><code>maxAge</code></td><td>Максимальний дозволений вік документа, у вигляді пари <code>value</code> + <code>unit</code>. Можливі значення <code>unit</code>: <code>"days"</code>, <code>"weeks"</code>, <code>"months"</code>, <code>"years"</code>.</td><td>-</td><td>&#x3C;object></td></tr></tbody></table>

**Fields (Поля)**

Кожен об'єкт у масиві `fields` визначає окрему одиницю даних для витягування з документа.

<table><thead><tr><th width="147.1171875">Параметр</th><th width="462.48828125">Опис</th><th width="178.23828125">За замовчуванням</th><th>Тип</th></tr></thead><tbody><tr><td><code>key</code></td><td>Унікальний ідентифікатор поля в межах кроку. Використовується для посилання на витягнуте значення у виводі API. Обов'язково.</td><td>-</td><td>&#x3C;string></td></tr><tr><td><code>type</code></td><td>Визначає, як перевіряється та форматується витягнуте значення. Можливі значення: <code>"text"</code>, <code>"number"</code>, <code>"date"</code>, <code>"boolean"</code>, <code>"email"</code>, <code>"phone"</code>, <code>"currency"</code>, <code>"money"</code>, <code>"iban"</code> <code>"taxId"</code>, <code>"address"</code>, <code>"percentage"</code>, <code>"other"</code></td><td>-</td><td>&#x3C;string></td></tr><tr><td><code>otherTypeLabel</code></td><td>Довільний текстовий опис даних, які містить це поле. Використовується лише коли <code>type</code> дорівнює <code>"other"</code>; якщо залишити порожнім, ШІ розглядає поле як вільний текст без перевірки формату.</td><td>null</td><td>&#x3C;string></td></tr><tr><td><code>label</code></td><td>Назва поля для відображення, використовується для ідентифікації в документі та показується в деталях сесії. Необов'язкова, якщо надано <code>extractionHint</code>.</td><td>-</td><td>&#x3C;string></td></tr><tr><td><code>alternativeNames</code></td><td>Альтернативні терміни через кому, під якими це поле може з'являтися в документі (наприклад, «Sex, Male/Female» для поля Gender). Використовується лише для інформування витягування, не показується в перегляді чи виводі API.</td><td>null</td><td>&#x3C;string></td></tr><tr><td><code>mandatory</code></td><td>Чи позначається сесія, якщо це поле не може бути витягнуте.</td><td><code>false</code></td><td>&#x3C;boolean></td></tr><tr><td><code>confidenceThreshold</code></td><td>Перевизначає поріг достовірності на рівні кроку для цього конкретного поля.</td><td>Успадковує значення за замовчуванням кроку</td><td>&#x3C;number></td></tr><tr><td><code>extractionHint</code></td><td>Додатковий контекст про це поле, наданий ШІ при витягуванні його значення. Рекомендується англійською мовою незалежно від мови документа. Необов'язково, якщо надано <code>label</code>.</td><td>null</td><td>&#x3C;string></td></tr></tbody></table>

> **Примітка:** Для кожного поля має бути надано принаймні одне з двох — `label` або `extractionHint`, щоб ШІ мав що шукати.

**Приклад cURL:**

Приклад використання cURL із кроком `anydoc-reader`:

<details>

<summary><em>Розгорнути, щоб переглянути приклад</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": "anydoc-reader",
            "key": "anydoc-payslip-1",
            "title": { "en": "AnyDoc upload" },
            "description": { "en": "Upload your most recent payslip so we can confirm your stated income." },
            "documentType": "Payslip",
            "allowedFormats": ["pdf", "image"],
            "pageConfiguration": "multiple",
            "pageCount": 2,
            "documentValidity": {
                "enabled": true,
                "dateField": "issue-date",
                "maxAge": { "value": 3, "unit": "months" }
            },
            "language": "en",
            "extractionHint": "This is a European payroll slip. Salary figures may use either comma or period as decimal separator.",
            "confidenceThreshold": 80,
            "retryLimit": 3,
            "fields": [
                { "key": "employee-name", "type": "text", "label": "Employee name", "mandatory": true },
                { "key": "issue-date", "type": "date", "label": "Issue date", "mandatory": true },
                { "key": "net-salary", "type": "money", "label": "Net salary", "mandatory": true, "confidenceThreshold": 90 }
            ]
        }
    ]
}'
```

</details>

***

### **SSN verification (Перевірка SSN)**

Крок SSN verification перевіряє номер соціального страхування (Social Security Number) користувача як частину процесу ідентифікації.

**Конфігурації кроку SSN verification:**

* **Заголовок:** `SSN verification`
* **Тип**: `ssn`
* **Ключ**: визначається клієнтом, має залишатися унікальним у межах сесії

**Приклад cURL:**

Приклад використання cURL із прапорцями **`return_url`** та **`language`** та кроком **`ssn`**:

<details>

<summary><em>Розгорнути, щоб переглянути приклад</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": "ssn",
            "title": {
                "en": "SSN verification"
            },
            "key": "ssn-gk466q"
        }
    ]
}'
```

</details>

***

### User questionnaire (Опитувальник користувача)

Крок user questionnaire дозволяє збирати власний ввід користувача як частину потоку верифікації. Він підтримує різні типи запитань та надає багатомовну підтримку для заголовків та описів. Усі відповіді зберігаються в сесії верифікації. Цей крок має дещо іншу структуру порівняно з іншими кроками.

**Конфігурації кроку User questionnaire:**

* `type`

  Має бути встановлено як `"user-questionnaire"`, щоб визначити цей крок як блок опитувальника користувача.
* `key`\
  Визначений клієнтом унікальний ключ для цього кроку опитувальника. Має залишатися унікальним у межах однієї сесії, щоб уникнути конфліктів.
* `title`\
  Основний заголовок опитувальника, що відображається в інтерфейсі користувача.\
  Завжди має надаватися як \<object> з кодами мов як ключами (наприклад, `"en"`), навіть якщо використовується лише одна мова. Це забезпечує узгодженість та підтримує майбутню локалізацію.
* `description`\
  Текст, що відображається під заголовком в інтерфейсі користувача, надаючи контекст чи інструкції.\
  Завжди має бути \<object> кодів мов. Той самий формат та правила, що й для `title`.
* `questions`\
  Масив об'єктів запитань, які будуть показані користувачеві.\
  Підтримувані типи запитань включають:
  * `string`: **Коротка відповідь** – Користувач вводить коротку текстову відповідь.
  * `multiple-choice`: **Прапорці** – Дозволяє користувачеві обрати один або декілька варіантів.
  * `options`: **Radio** – Користувач обирає один варіант зі списку.
  * `dropdown` : **Випадаючий список** – Користувач обирає один або декілька варіантів із випадаючого меню.
  * `file`: **Завантаження файлу** – Дозволяє користувачеві завантажити файл як відповідь.
  * `attachment`: **Вкладення -** Дозволяє прикріплювати файли динамічно (через API/конфігурацію) або за сесією. Залежно від конфігурації, файли можуть бути попередньо прикріплені для користувача або завантажені оператором під час сесії.
* `successButtonTitle`\
  Визначає мітку кнопки підтвердження, показаної в кінці опитувальника.\
  Також має бути \<object> кодів мов, навіть якщо використовується лише одна мова.\
  Якщо будь-яке запитання позначено як `"mandatory": true`, кнопка залишатиметься вимкненою, доки не будуть дані відповіді на всі обов'язкові запитання.

**Questions (Запитання)**

Кожне запитання в масиві `questions` підтримує набір параметрів, що визначають його поведінку та вигляд для користувача. Ось розбір усіх підтримуваних властивостей:

* `type`\
  Визначає тип запитання.\
  Підтримувані значення:
  * `string` – Коротка відповідь
  * `multiple-choice` – Прапорець (множинний вибір)
  * `options` – Перемикачі Radio (одиничний вибір)
  * `dropdown` – Випадаюче меню (одиничний або множинний вибір)
  * `file` – Завантаження файлу
  * `attachment` - Прикріпити файли та поділитися з кінцевим користувачем
* `title`\
  Багатомовний \<object>, що представляє мітку запитання.\
  Приклад:

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

* `key`\
  **Унікальний ідентифікатор** для запитання в межах того самого опитувальника. Визначається клієнтом та використовується для посилання та мапінгу даних.
* `mandatory`\
  Вказує, чи має запитання бути відповіджене, перш ніж користувач зможе продовжити.
  * Значення: `true` або `false`
* `answer`\
  Дозволяє **попередньо встановити відповідь** для користувача.

  * `string`: Простий текстовий рядок (наприклад, `"John Doe"`).
  * `options`: Один ключ варіанту (наприклад, `"opt_a"`).
  * `multiple-choice`: Масив ключів варіантів (наприклад, `["opt_a", "opt_c"]`).
  * `dropdown`: Не застосовується.
  * `file`: Не застосовується.
  * `attachment`: Масив ID файлів

  *Примітка: Кінцеві користувачі* можуть змінювати попередньо заповнені відповіді, якщо не увімкнено `readOnly`.
* `readOnly`\
  Показує запитання в **режимі, недоступному для редагування**. Користувачі можуть переглядати запитання та відповідь, але не можуть їх змінити.
  * Значення: `true` або `false`
* `showConditions`\
  Визначає **правило умовного показу** для запитання, на основі відповіді на попереднє запитання.
  * `questionKey` Ключ контролюючого запитання.
  * `answer` Ключ відповіді (для radio/checkbox) або конкретний текст (для string)

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

* `multiple`\
  Специфічно для типу `dropdown`.
  * Якщо `true`, користувач може обрати **декілька значень** із випадаючого списку.
  * Значення: `true` або `false`

**Options (Варіанти)**

Варіанти використовуються виключно в запитаннях типу `multiple-choice`, `options` та `dropdown`. Вони визначають вибіркові варіанти, з яких користувач може обрати.

Кожне запитання, що підтримує варіанти, має включати такий параметр:

* `options`\
  Масив об'єктів варіантів для запитання. Кожен об'єкт має включати таке:
* `title`\
  Текстова мітка для варіанту, показана користувачеві під час потоку верифікації.\
  Завжди має надаватися як \<object> з кодами мов як ключами, навіть якщо використовується лише одна мова.\
  Це забезпечує узгодженість у багатомовних потоках.\
  Приклад:

```json
{
  "en": "Self-employed"
}
```

* `key`\
  Унікальний ідентифікатор для варіанту в межах опитувальника.\
  Це значення використовується для посилання в попередньо встановлених відповідях, умовах та даних сесії.\
  Має бути унікальним у межах того самого опитувальника, щоб уникнути конфліктів.

**Список параметрів з прикладами:**

<table data-full-width="true"><thead><tr><th width="133">Параметр</th><th width="217">Опис</th><th width="100">За замовчуванням</th><th width="118">Тип</th><th>Приклад</th></tr></thead><tbody><tr><td><code>key</code></td><td><p>Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії.</p><p>Рекомендується використовувати ключ, що коротко описує опитувальник.</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>Заголовок опитувальника користувача, показаний як заголовок блоку з боку користувача. Заголовок може бути &#x3C;object>, що містить різні <strong>мови</strong>, дозволяючи показувати заголовок обраною мовою під час потоку верифікації.</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>Опис, що з'являється під заголовком з боку користувача. Подібно до заголовка, опис може бути &#x3C;object>, що містить різні <strong>мови</strong>, тож він може відображатися обраною мовою під час потоку верифікації.</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>Масив запитань наступних типів: <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>Вказує, чи потрібно обов'язково відповісти на запитання.<br></p><p>Можливі значення:</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>Дозволяє попередньо встановити відповідь на запитання.</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>Показує запитання, але обмежує взаємодію.</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>Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.</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>Заголовок кнопки дії в опитувальнику. Якщо запитання є обов'язковими, кнопка деактивується, доки користувач не завершить опитувальник.</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:**

<details>

<summary><em>Розгорнути, щоб переглянути приклад user-questionnaire</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>

**Тип запитання: Коротка відповідь**

Доступні параметри:

<table data-full-width="true"><thead><tr><th width="133">Параметр</th><th width="217">Опис</th><th width="100">За замовчуванням</th><th width="117.875">Тип</th><th>Приклад</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>Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії.</p><p>Рекомендується використовувати ключ, що коротко описує запитання.</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>Заголовок є &#x3C;object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.</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>Визначає очікувану структуру відповіді користувача. Визначає, як перевіряється ввід.</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><pre><code>"format": {
    "type": "contactNumber"
}
</code></pre></td></tr><tr><td><code>mandatory</code></td><td><p>Вказує, чи потрібно обов'язково відповісти на запитання.<br></p><p>Можливі значення:</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>Дозволяє попередньо встановити відповідь на запитання.<br>Відповідь є &#x3C;object> мов, тож якщо користувач змінює мову під час потоку верифікації, попередньо заповнену відповідь можна показувати різними мовами.</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>Показує запитання, але обмежує взаємодію.</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>Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.</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>Розгорнути, щоб переглянути приклад запитання КОРОТКА ВІДПОВІДЬ</em></summary>

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

</details>

***

**Тип запитання: Прапорець (Checkbox)**

Доступні параметри:

<table data-full-width="true"><thead><tr><th width="133">Параметр</th><th width="217">Опис</th><th width="100">За замовчуванням</th><th width="118">Тип</th><th>Приклад</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>Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії.</p><p>Рекомендується використовувати ключ, що коротко описує запитання.</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>Заголовок є &#x3C;object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.</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><ul><li>"<strong>title</strong>" : Заголовок варіанту. Заголовок є &#x3C;object>, що містить різні мови, дозволяючи показувати варіант обраною мовою під час потоку верифікації.</li><li>"<strong>key</strong>": Ключ для варіанту, обраний клієнтом. Має залишатися унікальним у межах одного опитувальника.</li></ul></td><td>-</td><td>&#x3C;array></td><td><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>Вказує, чи потрібно обов'язково відповісти на запитання.<br></p><p>Можливі значення:</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>Дозволяє попередньо встановити відповідь на запитання.<br>Відповідь є &#x3C;array> <strong>ключів варіантів</strong>, призначених для цього запитання.</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>Показує запитання, але обмежує взаємодію.</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>Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.</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>Розгорнути, щоб переглянути приклад запитання ПРАПОРЕЦЬ</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>

***

**Тип запитання: Radio**

Доступні параметри:

<table data-full-width="true"><thead><tr><th width="133">Параметр</th><th width="217">Опис</th><th width="100">За замовчуванням</th><th width="118">Тип</th><th>Приклад</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>Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії.</p><p>Рекомендується використовувати ключ, що коротко описує запитання.</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>Заголовок є &#x3C;object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.</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><ul><li>"<strong>title</strong>" : Заголовок варіанту. Заголовок є &#x3C;object>, що містить різні мови, дозволяючи показувати варіант обраною мовою під час потоку верифікації.</li><li>"<strong>key</strong>": Ключ для варіанту, обраний клієнтом. Має залишатися унікальним у межах одного опитувальника.</li></ul></td><td>-</td><td>&#x3C;array></td><td><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>Вказує, чи потрібно обов'язково відповісти на запитання.<br></p><p>Можливі значення:</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>Дозволяє попередньо встановити відповідь на запитання.<br>Відповідь є &#x3C;string> <strong>ключа варіанту</strong>, призначеного для цього запитання.</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>Показує запитання, але обмежує взаємодію.</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>Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.</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>Розгорнути, щоб переглянути приклад запитання RADIO</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>

***

**Тип запитання: Випадаючий список**

Доступні параметри:

<table data-full-width="true"><thead><tr><th width="133">Параметр</th><th width="217">Опис</th><th width="100">За замовчуванням</th><th width="118">Тип</th><th>Приклад</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>Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії.</p><p>Рекомендується використовувати ключ, що коротко описує запитання.</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>Заголовок є &#x3C;object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.</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><ul><li>"<strong>title</strong>" : Заголовок варіанту. Заголовок є &#x3C;object>, що містить різні мови, дозволяючи показувати варіант обраною мовою під час потоку верифікації.</li><li>"<strong>key</strong>": Ключ для варіанту, обраний клієнтом. Має залишатися унікальним у межах одного опитувальника.</li></ul></td><td>-</td><td>&#x3C;array></td><td><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>Вказує, чи потрібно обов'язково відповісти на запитання.<br></p><p>Можливі значення:</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>Вказує, чи запитання є одиничним чи множинним вибором.</p><p>Можливі значення:</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>Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.</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>Розгорнути, щоб переглянути приклад запитання ВИПАДАЮЧИЙ СПИСОК</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>

***

**Тип запитання: Завантаження файлу**

Доступні параметри:

<table data-full-width="true"><thead><tr><th width="133">Параметр</th><th width="217">Опис</th><th width="100">За замовчуванням</th><th width="118">Тип</th><th>Приклад</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>Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії.</p><p>Рекомендується використовувати ключ, що коротко описує запитання.</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>Заголовок є <code>&#x3C;object></code> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.</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>Опис, що з'являється під заголовком. Подібно до заголовка, опис може бути &#x3C;object>, що містить різні мови, тож він може відображатися обраною мовою під час потоку верифікації.</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>Вказує, чи потрібно обов'язково відповісти на запитання.<br></p><p>Можливі значення:</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>Вказує типи файлів, які користувач може завантажувати.<br><br>Можливі значення:<br><code>pdf</code>, <code>image</code>.</td><td>[ <code>"pdf"</code>, <code>"image"</code> ]</td><td>&#x3C;array></td><td><pre class="language-json"><code class="lang-json">"fileTypes": [
    "pdf",
    "image"
]
</code></pre></td></tr><tr><td><code>filesMaxCount</code></td><td>Вказує максимальну кількість файлів, які користувач може завантажити.<br><br>Можливі значення:<br>Число від 1 до 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>Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.</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>Розгорнути, щоб переглянути приклад запитання ЗАВАНТАЖЕННЯ ФАЙЛУ</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>

***

**Тип запитання: Вкладення**

Тип запитання **Attachment** дозволяє прикріпляти файли до опитувальника. Він підтримує два основних випадки використання:

1. **Вкладення, додані оператором за сесією**\
   Оператор завантажує файли під час або перед сесією верифікації та ділиться ними з кінцевим користувачем.
2. **Попередньо визначені вкладення з конфігурації чи API**\
   Файли завантажуються в інтерфейсі конфігурації або динамічно надаються через API. Ці файли автоматично включаються в майбутні сесії.

**Поведінка**

* Вкладення видимі як оператору, так і кінцевому користувачу.
* Коли файли надані через API (`answer`) чи конфігурацію, вони з'являться при відкритті опитувальника.
* Залежно від налаштувань, оператору може бути дозволено або заборонено змінювати вкладення після того, як користувач підтвердив опитувальник.

Доступні параметри:

<table data-full-width="true"><thead><tr><th width="133">Параметр</th><th width="217">Опис</th><th width="100">За замовчуванням</th><th width="118">Тип</th><th>Приклад</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>Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії.</p><p>Рекомендується використовувати ключ, що коротко описує запитання.</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>Заголовок є <code>&#x3C;object></code> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.</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>Опис, що з'являється під заголовком. Подібно до заголовка, опис може бути &#x3C;object>, що містить різні мови, тож він може відображатися обраною мовою під час потоку верифікації.</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>Вказує типи файлів, які користувач може завантажувати.<br><br>Можливі значення:<br><code>pdf</code>, <code>image</code>.</td><td>[ <code>"pdf"</code>, <code>"image"</code> ]</td><td>&#x3C;array></td><td><pre class="language-json"><code class="lang-json">"fileTypes": [
    "pdf",
    "image"
]
</code></pre></td></tr><tr><td><code>filesMaxCount</code></td><td>Вказує максимальну кількість файлів, які користувач може завантажити.<br><br>Можливі значення:<br>Число від 1 до 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>Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.</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>Контролює, як додаються файли:<br>• <strong>true</strong> – оператор завантажує файли за сесією.<br>• <strong>false</strong> – файли надаються лише через конфігурацію чи API.</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>Якщо <strong>false</strong>, оператор не може редагувати вкладення після того, як користувач підтвердив опитувальник.<br>Якщо <strong>true</strong>, оператор все ще може завантажувати або видаляти файли.</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>Розгорнути, щоб переглянути приклад запитання ВКЛАДЕННЯ</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 (Опитувальник оператора)

Опитувальник оператора є частиною сесії та призначений для заповнення **оператором**, під час або після дзвінка верифікації. Він дозволяє операторам збирати конкретну інформацію або надавати ручний ввід.\
Його структура тісно віддзеркалює опитувальник користувача, з основною відмінністю в тому, хто заповнює форму.

**Конфігурації кроку Operator questionnaire:**

* `type`\
  Має бути встановлено як `"operator-questionnaire"`, щоб визначити цей крок як форму для оператора.
* `key`\
  Унікальний ідентифікатор для кроку опитувальника оператора. Цей ключ визначається клієнтом і має залишатися унікальним у межах однієї сесії.
* `title`\
  Назва розділу, як показано в інтерфейсі оператора.\
  Завжди має бути \<object> з кодами мов як ключами, навіть якщо використовується лише одна мова.\
  Приклад:

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

* `description`\
  Текст, показаний під заголовком, використовується для надання контексту чи інструкцій оператору.\
  Також має надаватися як `<object>` кодів мов.
* `questions`\
  Масив об'єктів запитань, які визначають поля, які оператор заповнюватиме.\
  Підтримувані типи запитань включають:
  * `string`: **Коротка відповідь** – Оператор вводить коротку текстову відповідь.
  * `multiple-choice`: **Прапорець** – Оператор обирає одне або декілька значень зі списку варіантів.
  * `options`: **Radio** – Оператор обирає один варіант із заздалегідь визначеного набору.
  * `dropdown`: **Випадаюче меню** – Оператор обирає один або декілька варіантів із випадаючого списку, залежно від конфігурації.
  * `file`: **Завантаження файлу** – Оператор завантажує один або декілька файлів (наприклад, документи чи зображення) як частину опитувальника.

**Questions (Запитання)**

Кожне запитання в опитувальнику оператора має бути визначено як об'єкт у масиві `questions`. Для кожного запитання підтримуються такі параметри:

* `type`\
  Тип запитання. Підтримувані значення:
  * `string` – Коротка відповідь
  * `multiple-choice` – Прапорець
  * `options` – Перемикачі Radio
  * `dropdown` – Випадаючий список
  * `file` – Завантаження файлу
* `title`\
  Заголовок запитання. Немає обмежень щодо довжини чи символів.\
  Завжди має надаватися як \<object> кодів мов (наприклад, `"en"`, `"de"`), навіть якщо використовується лише одна мова.\
  Приклад:

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

* `key`\
  Унікальний ідентифікатор для запитання, визначений клієнтом. Має бути унікальним у межах того самого опитувальника.
* `mandatory`\
  \<boolean>. Вказує, чи потрібно відповісти на запитання перед поданням опитувальника.\
  За замовчуванням `false`.
* `answer`\
  Дозволяє **попередньо встановити відповідь** для оператора.

  * Для `string`: Простий текстовий рядок (наприклад, `"Invalid ID"`).
  * Для `options`: Один ключ варіанту (наприклад, `"opt_a"`).
  * Для `multiple-choice`: Масив ключів варіантів (наприклад, `["opt_a", "opt_c"]`).
  * Для `dropdown`: Не застосовується.
  * Для `file`: Не застосовується.

  *Примітка:* Оператори можуть змінювати попередньо заповнені відповіді, якщо не увімкнено `readOnly`.
* `readOnly`\
  Показує запитання в **режимі, недоступному для редагування**. Оператори можуть переглядати запитання та відповідь, але не можуть їх змінити.
* `showConditions`\
  Визначає **правило умовного показу** для запитання, на основі відповіді на попереднє запитання.
  * `questionKey` Ключ контролюючого запитання.
  * `answer` Ключ відповіді (для radio/checkbox) або конкретний текст (для string).

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

**Options (Варіанти)**

Варіанти використовуються виключно в запитаннях типу `multiple-choice`, `options` та `dropdown`. Вони визначають вибіркові варіанти, з яких користувач може обрати.

Кожне запитання, що підтримує варіанти, має включати такий параметр:

* `options`\
  Масив об'єктів варіантів для запитання. Кожен об'єкт має включати таке:
* `title`\
  Текстова мітка для варіанту, показана оператору під час сесії верифікації. Завжди має надаватися як \<object> з кодами мов як ключами, навіть якщо використовується лише одна мова. Це забезпечує узгодженість у багатомовних потоках.

```json
{
  "en": "ID card"
}
```

* `key`\
  Унікальний ідентифікатор для варіанту в межах опитувальника.\
  Це значення використовується для посилання в попередньо встановлених відповідях, умовах та даних сесії.\
  Має бути унікальним у межах того самого опитувальника, щоб уникнути конфліктів.

**Список параметрів з прикладами:**

<table data-full-width="true"><thead><tr><th width="133">Параметр</th><th width="217">Опис</th><th width="100">За замовчуванням</th><th width="118">Тип</th><th>Приклад</th></tr></thead><tbody><tr><td><code>key</code></td><td><p>Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії.</p><p>Рекомендується використовувати ключ, що коротко описує опитувальник.</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>Заголовок опитувальника оператора, показаний як назва вкладки в сесії. Заголовок може бути <code>&#x3C;object></code>, що містить різні <strong>мови</strong>, дозволяючи показувати заголовок обраною мовою.</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>Подібно до заголовка, опис може бути &#x3C;object>, що містить різні <strong>мови</strong>, тож він може відображатися обраною мовою.</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>Масив запитань наступних типів: <code>string</code>, <code>multiple-choice</code> та <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>Вказує, чи потрібно обов'язково відповісти на запитання.<br></p><p>Можливі значення:</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>Дозволяє попередньо встановити відповідь на запитання.</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>Показує запитання, але обмежує взаємодію.</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>Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.</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:**

<details>

<summary><em>Розгорнути, щоб переглянути приклад operator-questionnaire</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 (Додаткові параметри сесії)

Окрім `steps` та `flags`, ви також можете налаштувати додаткові параметри при створенні сесії. Ці параметри допомагають з ідентифікацією та керуванням сесією.

<table data-full-width="true"><thead><tr><th width="218">Назва параметра</th><th width="437">Опис</th><th width="216">За замовчуванням</th><th width="121">Тип</th></tr></thead><tbody><tr><td><code>name</code></td><td>Користувацька мітка сесії, показана в панелі керування до завершення верифікації користувачем. Після завершення сесії це значення замінюється іменем верифікованого користувача (якщо доступне).</td><td>null</td><td>&#x3C;string></td></tr><tr><td><code>clientUserId</code></td><td>Унікальний ідентифікатор, що використовується для зв'язку сесії з конкретним користувачем у вашій системі. Корисно для групування сесій чи синхронізації з внутрішніми ID користувачів чи облікових записів.</td><td>null</td><td>&#x3C;string></td></tr><tr><td><code>groupId</code></td><td>Визначає групу, призначену для сесії. Наприклад, під час відеодзвінка лише учасники цієї вказаної групи зможуть отримати дзвінок.</td><td>null</td><td>&#x3C;string></td></tr><tr><td><code>scheduleStartTime</code></td><td>Дата та час, коли сесія стає доступною кінцевому користувачу. До цього часу сесію неможливо розпочати.<br>Формат: ISO 8601 — наприклад, <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>Дата та час, після якого сесія більше недоступна кінцевому користувачу.<br>Формат: ISO 8601 — наприклад, <code>"2024-06-20T09:00:00.000Z"</code></td><td>null</td><td>&#x3C;string> (ISO 8601 datetime)</td></tr></tbody></table>

**Приклад:**

```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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.identomat.com/identomat-documentation-ukr/posibnik-dlya-rozrobnikiv/kyc-know-your-customer.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.