KYB (Know Your Business)

Потік KYB перевіряє легітимність суб'єктів господарювання, включно з даними компанії, реєстраційними документами та пов'язаними представниками.

Потік KYB призначений для збору та перевірки інформації про компанію, включно з даними про саму організацію, її бенефіціарів та представників. Він гарантує, що всі відповідні суб'єкти ідентифіковані та перевірені перед завершенням процесу onboarding.

Потік KYB складається з трьох основних кроків:

1

Company data (Дані компанії)

2

Beneficiaries (Бенефіціари)

3

Review (Перегляд)

Кожен крок повністю настроюваний і може мати власні параметри.

Flags (Прапорці)

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

Назва прапорця	Опис	За замовчуванням	Тип
skip_face	Пропускає крок liveness, якщо він вже існує у визначених кроках. Запобігає дублюванню при використанні власних потоків.	false	<boolean>
skip_document	Пропускає крок identity-document, якщо він вже існує у визначених кроках. Запобігає дублюванню при використанні власних потоків.	false	<boolean>
return_url	URL для перенаправлення користувача після завершення процесу ідентифікації. Якщо не вказано, вважається, що сесія вбудована в iframe.	null	<string>
language	Код мови інтерфейсу користувача. Підтримувані значення: "es", "ka", "uk", "ru", "uz", "it", "gr", "tr", "ro", "ar", "de", "pl", "hi", "bn", "az", "ja", "pt", "fr", "kk", "sv"	"en"	<string>
skip_desktop	Обмежує сесії лише мобільними пристроями. Якщо ініційовано на комп'ютері, показується QR-код для перенесення сесії на мобільний пристрій.	false	<boolean>
switch_device_url	Користувацький URL для відображення в QR-коді, коли камера недоступна або заблокована. Якщо не вказано або порожньо, QR-код не відображатиметься.	null	<string>
restrict_url_sharing	Забороняє використання URL сесії на іншому браузері чи пристрої. Якщо true, QR-код не з'явиться, коли доступ до камери заборонено — якщо тільки switch_device_url також не визначено.	false	<boolean>

Steps (Кроки)

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

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

Властивість	Опис
type	Тип конкретного кроку (див. список підтримуваних типів кроків нижче).
key	Унікальний ідентифікатор кроку. Цей ключ можна налаштувати, але він має залишатися унікальним у межах сесії.
flags	Прапорці конфігурації, специфічні для кроку, які контролюють поведінку цього кроку.
title	Користувацький заголовок, наданий клієнтом, що відображається користувачеві під час цього кроку в інтерфейсі.

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

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

• Language (Мова)

• Company data (Дані компанії)

• Beneficiaries (Бенефіціари)

• Review (Перегляд)

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

---

Language (Мова)

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

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

• Заголовок: Language

• Тип: language

• Ключ: language

• Масив languages

Прапорець	Опис	За замовчуванням	Тип
languages	Масив кодів мов для відображення. Якщо залишити порожнім, показуються всі підтримувані мови. "en", "ka", "es", "uk", "gr", "it", "de", "ru", "uz", "ro", "tr", "ar", "pl", "bn", "hi", "hy", "az", "ja", "pt", "fr", "kk", "sv"	Усі	Array<string>

Розгорнути, щоб переглянути приклад

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

---

Company data (Дані компанії)

Цей крок збирає основну інформацію про компанію.

• Заголовок: Company data

• Опис: Follow the simple steps below

• Тип: company

• Ключ: company

• Поля:

  • Назва компанії (завжди обов'язкове)

  • Реєстраційний номер (завжди обов'язкове)

  • Країна реєстрації (завжди обов'язкове)

  • Тип юридичної особи

  • Юридична адреса

  • ПДВ / Податковий ID

  • Дата заснування

  • Контактний номер

  • Контактна email-адреса

Приклад кроку:

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

Параметри кроку:

Параметр	Опис	Тип
type	Тип кроку. Має бути company.	<string>
key	Унікальний ідентифікатор кроку.	<string>
title	Локалізований текст заголовка, що відображається користувачеві як заголовок блоку. Заголовок може бути <object>, що містить різні мови, дозволяючи показувати заголовок обраною мовою під час потоку.	<object>
description	Опис, що з'являється під заголовком з боку користувача. Подібно до заголовка, опис може бути <object>, що містить різні мови, тож він може відображатися обраною мовою під час потоку.	<object>
fields	Список полів, які збиратимуться під час цього кроку.	<array>

Поля:

Приклад:

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

Поле	Опис	Тип вводу
companyEntityType	Обов'язкове поле. Тип юридичної особи. Варіанти включають: Товариство з обмеженою відповідальністю Публічна компанія Індивідуальний підприємець Партнерство Корпорація Траст Приватний фонд Благодійна організація Некомерційна організація Інше	Випадаючий список
companyName	Обов'язкове поле. Офіційна зареєстрована назва компанії.	Текстове поле
registrationNumber	Обов'язкове поле. Реєстраційний номер компанії.	Текстове поле
registrationCountry	Обов'язкове поле. Країна реєстрації. Варіанти: список усіх країн.	Випадаючий список
legalAddress	Зареєстрована юридична адреса компанії.	Текстове поле
taxId	Податковий ідентифікаційний номер.	Текстове поле
dateOfIncorporation	Дата заснування компанії.	Вибір дати
contactNumber	Контактний номер телефону компанії.	Текстове поле
email	Контактна email-адреса компанії.	Текстове поле

---

Beneficiaries (Бенефіціари)

Крок Beneficiaries збирає інформацію про всіх осіб чи компаній із ролями в організації.

Кожна роль може ініціювати потік верифікації KYC або KYB.

Підтримувані ролі:

• Shareholder (Акціонер) – може бути фізичною особою або іншою компанією

• UBOs (Кінцевий бенефіціарний власник) – завжди фізична особа з правом власності/контролю

• Director (Директор) – окремий член ради директорів

• Representative (Представник) – уповноважена фізична особа, що діє від імені компанії

• Other (Інше) – власна роль (потребує назви посади)

Приклад кроку:

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

Параметри кроку:

Параметр	Опис	Тип
type	Тип кроку. Має бути beneficiaries.	<string>
key	Унікальний ідентифікатор кроку.	<string>
title	Локалізований текст заголовка, що відображається користувачеві як заголовок блоку. Заголовок може бути <object>, що містить різні мови, дозволяючи показувати заголовок обраною мовою під час потоку.	<object>
description	Опис, що з'являється під заголовком з боку користувача. Подібно до заголовка, опис може бути <object>, що містить різні мови, тож він може відображатися обраною мовою під час потоку.	<object>
kycConfigId	ID конфігурації KYC, що застосовується до фізичних осіб.	<string>
kybConfigId	ID конфігурації KYB, що застосовується до компаній.	<string>
roles	Визначає ролі (shareholder, ubo, director, representative, other).	<object>

Роль: Shareholder (Акціонер)

• Може бути фізичною особою або компанією.

• verification: true → ініціює потік верифікації

  • Фізична особа → KYC (kycConfigId)

  • Компанія → KYB (kybConfigId)

Важливо: Для потоків верифікації акціонерів потрібні попередньо створені конфігурації KYC та KYB. Ці конфігурації визначають, які кроки верифікації (наприклад, завантаження документа, селфі, опитувальник) будуть застосовані під час процесу. Щоб дізнатися, як створювати та керувати конфігураціями KYC, див. Посібник для розробників KYC або Посібник з конфігурації KYC.

Приклад ролі:

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

Поля Shareholder:

Поле	Опис	Тип вводу	Застосовується до
ownershipPercentage	Відсоток володіння компанією.	Текстове поле	Компанія / Фізична особа
companyName	Обов'язкове поле. Офіційна зареєстрована назва компанії.	Текстове поле	Компанія
registrationNumber	Обов'язкове поле. Реєстраційний номер компанії-акціонера.	Текстове поле	Компанія
registrationCountry	Обов'язкове поле. Країна реєстрації. Варіанти: список усіх країн.	Випадаючий список	Компанія
companyEntityType	Обов'язкове поле. Тип юридичної особи. Варіанти включають: Товариство з обмеженою відповідальністю Публічна компанія Індивідуальний підприємець Партнерство Корпорація Траст Приватний фонд Благодійна організація Некомерційна організація Інше	Випадаючий список	Компанія
legalAddress	Зареєстрована юридична адреса компанії-акціонера.	Текстове поле	Компанія
taxId	Податковий ідентифікаційний номер.	Текстове поле	Компанія
dateOfIncorporation	Дата заснування компанії.	Вибір дати	Компанія
website	Вебсайт компанії.	Поле вводу	Компанія
contactNumber	Контактний номер телефону.	Текстове поле	Компанія / Фізична особа
email	Контактна email-адреса.	Текстове поле	Компанія / Фізична особа
firstName	Обов'язкове поле. Ім'я фізичної особи.	Текстове поле	Фізична особа
lastName	Обов'язкове поле. Прізвище фізичної особи.	Текстове поле	Фізична особа
dateOfBirth	Обов'язкове поле. Дата народження фізичної особи.	Вибір дати	Фізична особа

Роль: UBOs

• Завжди фізична особа.

• verification: true → ініціює потік KYC (kycConfigId)

Важливо: Для потоків верифікації UBO потрібна попередньо створена конфігурація KYC. Ці конфігурації визначають, які кроки верифікації (наприклад, завантаження документа, селфі, опитувальник) будуть застосовані під час процесу. Щоб дізнатися, як створювати та керувати конфігураціями KYC, див. Посібник для розробників KYC або Посібник з конфігурації KYC.

Приклад ролі:

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

Поля UBOs:

Поле	Опис	Тип вводу
firstName	Обов'язкове поле. Ім'я фізичної особи.	Текстове поле
lastName	Обов'язкове поле. Прізвище фізичної особи.	Текстове поле
dateOfBirth	Обов'язкове поле. Дата народження фізичної особи.	Вибір дати
ownershipPercentage	Відсоток володіння компанією.	Текстове поле
contactNumber	Контактний номер телефону компанії.	Текстове поле
email	Контактна email-адреса компанії.	Текстове поле

Роль: Director (Директор)

• Завжди фізична особа.

• verification: true → ініціює потік KYC (kycConfigId)

Важливо: Для потоків верифікації директора потрібна попередньо створена конфігурація KYC. Ці конфігурації визначають, які кроки верифікації (наприклад, завантаження документа, селфі, опитувальник) будуть застосовані під час процесу. Щоб дізнатися, як створювати та керувати конфігураціями KYC, див. Посібник для розробників KYC або Посібник з конфігурації KYC.

Приклад ролі:

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

Поля Director:

Поле	Опис	Тип вводу
firstName	Обов'язкове поле. Ім'я фізичної особи.	Текстове поле
lastName	Обов'язкове поле. Прізвище фізичної особи.	Текстове поле
dateOfBirth	Обов'язкове поле. Дата народження фізичної особи.	Вибір дати
contactNumber	Контактний номер телефону компанії.	Текстове поле
email	Контактна email-адреса компанії.	Текстове поле

Роль: Representative (Представник)

• Завжди фізична особа.

• verification: true → ініціює потік KYC (kycConfigId)

Важливо: Для потоків верифікації представника потрібна попередньо створена конфігурація KYC. Ці конфігурації визначають, які кроки верифікації (наприклад, завантаження документа, селфі, опитувальник) будуть застосовані під час процесу. Щоб дізнатися, як створювати та керувати конфігураціями KYC, див. Посібник для розробників KYC або Посібник з конфігурації KYC.

Приклад ролі:

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

Поля Representative:

Поле	Опис	Тип вводу
firstName	Обов'язкове поле. Ім'я фізичної особи.	Текстове поле
lastName	Обов'язкове поле. Прізвище фізичної особи.	Текстове поле
dateOfBirth	Обов'язкове поле. Дата народження фізичної особи.	Вибір дати
contactNumber	Контактний номер телефону компанії.	Текстове поле
email	Контактна email-адреса компанії.	Текстове поле

Роль: Other (Інше)

• Завжди фізична особа.

• verification: true → ініціює потік KYC (kycConfigId)

Важливо: Для потоків верифікації ролі Other потрібна попередньо створена конфігурація KYC. Ці конфігурації визначають, які кроки верифікації (наприклад, завантаження документа, селфі, опитувальник) будуть застосовані під час процесу. Щоб дізнатися, як створювати та керувати конфігураціями KYC, див. Посібник для розробників KYC або Посібник з конфігурації KYC.

Приклад ролі:

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

Поля:

Поле	Опис	Тип вводу
positionName	Обов'язкове поле. Назва посади (наприклад, консультант)	Текстове поле
firstName	Обов'язкове поле. Ім'я фізичної особи.	Текстове поле
lastName	Обов'язкове поле. Прізвище фізичної особи.	Текстове поле
dateOfBirth	Обов'язкове поле. Дата народження фізичної особи.	Вибір дати
contactNumber	Контактний номер телефону компанії.	Текстове поле
email	Контактна email-адреса компанії.	Текстове поле

---

Review (Перегляд)

Крок Review показує зведення всіх зібраних даних про компанію та бенефіціарів перед поданням. Заявники можуть переглянути та відредагувати інформацію за потреби.

Приклад:

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

Цей крок дозволяє заявнику редагувати дані перед поданням.

Приклад KYB cURL:

Розгорнути, щоб переглянути приклад

curl https://widget.identomat.com/external-api/begin/ -d '{
"company_key": "your_company_key_here",
"flags": {
        "return_url": "https://example.com/",
        "language": "en"
},
  "steps": [
        {
          "type": "company",
          "key": "company",
          "title": {
            "en": "Company data"
          },
          "description": {
            "en": "Follow the simple steps below"
          },
          "fields": [
               { "type": "companyName", "mandatory": true },
               { "type": "companyEntityType", "mandatory": false },
               { "type": "registrationNumber", "mandatory": true },
               { "type": "registrationCountry", "mandatory": true },
               { "type": "legalAddress", "mandatory": true },
               { "type": "taxId", "mandatory": false },
               { "type": "dateOfIncorporation", "mandatory": false },
               { "type": "contactNumber", "mandatory": false },
               { "type": "email", "mandatory": false }
          ]
        },
        {
          "type": "beneficiaries",
          "key": "beneficiaries",
          "title": {
            "en": "Beneficiaries"
          },
          "description": {
            "en": "Enter information about the company's beneficiaries"
          },
          "kycConfigId": "687e0ba12cf633bd323cb0db",
          "kybConfigId": "687e0ba12cf633bd323cb0d2",
          "roles": {
            "shareholder": {
              "fields": [
                  { "type": "ownershipPercentage", "mandatory": false },
                  { "type": "companyName", "mandatory": true },
                  { "type": "companyEntityType", "mandatory": false },
                  { "type": "registrationNumber", "mandatory": true },
                  { "type": "registrationCountry", "mandatory": true },
                  { "type": "legalAddress", "mandatory": false },
                  { "type": "taxId", "mandatory": false },
                  { "type": "dateOfIncorporation", "mandatory": false },
                  { "type": "firstName", "mandatory": true },
                  { "type": "lastName", "mandatory": true },
                  { "type": "dateOfBirth", "mandatory": true },
                  { "type": "contactNumber", "mandatory": false },
                  { "type": "email", "mandatory": false }, 
                  { "type": "website", "mandatory": false }
              ],
              "verification": true
            },
            "ubo": {
              "fields": [
                { "type": "ownershipPercentage", "mandatory": true },
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
            },
            "director": {
              "fields": [
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
            },
            "representative": {
              "fields": [
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
            },
            "other": {
              "fields": [
                { "type": "positionName", "mandatory": true },
                { "type": "firstName", "mandatory": true },
                { "type": "lastName", "mandatory": true },
                { "type": "dateOfBirth", "mandatory": true },
                { "type": "email", "mandatory": false },
                { "type": "contactNumber", "mandatory": false }
              ],
              "verification": true
            }
          }
        },
        {
          "type": "kyb-review",
          "key": "kyb-review",
          "title": {
            "en": "Checking the data"
          },
          "subtitle": {
            "en": "Please check the information below to make sure everything is correct"
          }
        }
      ]
}'

---

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>, що представляє мітку запитання. Приклад:

"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)

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

• multiple Специфічно для типу dropdown.

  • Якщо true, користувач може обрати декілька значень із випадаючого списку.

  • Значення: true або false

Options (Варіанти)

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

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

• options Масив об'єктів варіантів для запитання. Кожен об'єкт має включати таке:

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

{
  "en": "Self-employed"
}

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

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

Параметр	Опис	За замовчуванням	Тип	Приклад
key	Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії. Рекомендується використовувати ключ, що коротко описує опитувальник.	-	<string>	"key": "terms-and-conditions"
title	Заголовок опитувальника користувача, показаний як заголовок блоку з боку користувача. Заголовок може бути <object>, що містить різні мови, дозволяючи показувати заголовок обраною мовою під час потоку верифікації.	-	<object>	"title": { "es": "Tu título", "en": "Your title" }
description	Опис, що з'являється під заголовком з боку користувача. Подібно до заголовка, опис може бути <object>, що містить різні мови, тож він може відображатися обраною мовою під час потоку верифікації.	-	<object>	"description": { "es": "Tu descripción", "en": "Your description" }
questions	Масив запитань наступних типів: string, multiple-choice , options, dropdown.	-	<array>	"questions": [ { "type": "string", "title": { "es": "Tu título", "en": "Your title" } "key": "question1", "mandatory": true }, { "type": "multiple-choice", "title": { "es": "Tu título", "en": "Your title" }, "key": "question2", "mandatory": false, "options": [ { "title": { "es": "Tu título", "en": "Your title" }, "key": "option1" }, { "title": { "es": "Tu título", "en": "Your title" }, "key": "option2" } ] } ]
mandatory	Вказує, чи потрібно обов'язково відповісти на запитання. Можливі значення: true, false	false	<boolean>	"mandatory": false
answer	Дозволяє попередньо встановити відповідь на запитання.	-	<string> or <array>	"answer": "option2"
readOnly	Показує запитання, але обмежує взаємодію.	false	<boolean>	"readOnly": false
showConditions	Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.	-	<object>	"showConditions": { "questionKey": "question1", "answer": "option1" }
successButtonTitle	Заголовок кнопки дії в опитувальнику. Якщо запитання є обов'язковими, кнопка деактивується, доки користувач не завершить опитувальник.	Confirm	<object>	"successButtonTitle": { "es": "Tu título", "en": "Your title" }

Приклад cURL:

Розгорнути, щоб переглянути приклад user-questionnaire

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

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

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

Параметр	Опис	За замовчуванням	Тип	Приклад
type	string	-	<string>	"type": "string"
key	Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії. Рекомендується використовувати ключ, що коротко описує запитання.	-	<string>	"key": "your-address"
title	Заголовок є <object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.	-	<object>	"title": { "es": "Tu título", "en": "Your title" }
mandatory	Вказує, чи потрібно обов'язково відповісти на запитання. Можливі значення: true, false	false	<boolean>	"mandatory": true
format	Визначає очікувану структуру відповіді користувача. Визначає, як перевіряється ввід.	free-text	<object>	"format": { "type": "free-text" } "format": { "type": "email" }
answer	Дозволяє попередньо встановити відповідь на запитання. Відповідь є <object> мов, тож якщо користувач змінює мову під час потоку верифікації, попередньо заповнену відповідь можна показувати різними мовами.	-	<object>	"answer": { "en": "This is a prefilled answer", "es":"Esta es una respuesta prellenada." }
readOnly	Показує запитання, але обмежує взаємодію.	false	<boolean>	"readOnly": true
showConditions	Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.	-	<object>	"showConditions": { "questionKey": "question1", "answer": "option1" }

Розгорнути, щоб переглянути приклад запитання КОРОТКА ВІДПОВІДЬ

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

---

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

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

Параметр	Опис	За замовчуванням	Тип	Приклад
type	multiple-choice	-	<string>	"type": "multiple-choice"
key	Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії. Рекомендується використовувати ключ, що коротко описує запитання.	-	<string>	"key": "check-two-answers"
title	Заголовок є <object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.	-	<object>	"title": { "es": "Tu título", "en": "Your title" }
options	Масив варіантів для запитання. Кожен варіант може мати: "title" : Заголовок варіанту. Заголовок є <object>, що містить різні мови, дозволяючи показувати варіант обраною мовою під час потоку верифікації. "key": Ключ для варіанту, обраний клієнтом. Має залишатися унікальним у межах одного опитувальника.	-	<array>	"options": [ { "title": { "en": "Identity Document", "es": "Documento de identidad" }, "key": "identity-document" }, { "title": { "en": "Proof of Address", "es": "Comprobante de domicilio" }, "key": "proof-of-address" ]
mandatory	Вказує, чи потрібно обов'язково відповісти на запитання. Можливі значення: true, false	false	<boolean>	"mandatory": true
answer	Дозволяє попередньо встановити відповідь на запитання. Відповідь є <array> ключів варіантів, призначених для цього запитання.	-	<array>	"answer": [ "option-1", "option-2" ]
readOnly	Показує запитання, але обмежує взаємодію.	false	<boolean>	"readOnly": true
showConditions	Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.	-	<object>	"showConditions": { "questionKey": "question1", "answer": "option1" }

Розгорнути, щоб переглянути приклад запитання ПРАПОРЕЦЬ

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

---

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

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

Параметр	Опис	За замовчуванням	Тип	Приклад
type	options	-	<string>	"type": "options"
key	Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії. Рекомендується використовувати ключ, що коротко описує запитання.	-	<string>	"key": "choose-one-answer"
title	Заголовок є <object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.	-	<object>	"title": { "es": "Tu título", "en": "Your title" }
options	Масив варіантів для запитання. Кожен варіант може мати: "title" : Заголовок варіанту. Заголовок є <object>, що містить різні мови, дозволяючи показувати варіант обраною мовою під час потоку верифікації. "key": Ключ для варіанту, обраний клієнтом. Має залишатися унікальним у межах одного опитувальника.	-	<array>	"options": [ { "title": { "en": "Identity Document", "es": "Documento de identidad" }, "key": "identity-document" }, { "title": { "en": "Proof of Address", "es": "Comprobante de domicilio" }, "key": "proof-of-address" ]
mandatory	Вказує, чи потрібно обов'язково відповісти на запитання. Можливі значення: true, false	false	<boolean>	"mandatory": true
answer	Дозволяє попередньо встановити відповідь на запитання. Відповідь є <string> ключа варіанту, призначеного для цього запитання.	-	<string>	"answer": "option-1"
readOnly	Показує запитання, але обмежує взаємодію.	false	<boolean>	"readOnly": true
showConditions	Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.	-	<object>	"showConditions": { "questionKey": "question1", "answer": "option1" }

Розгорнути, щоб переглянути приклад запитання RADIO

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

---

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

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

Параметр	Опис	За замовчуванням	Тип	Приклад
type	dropdown	-	<string>	"type": "dropdown"
key	Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії. Рекомендується використовувати ключ, що коротко описує запитання.	-	<string>	"key": "choose-from-list"
title	Заголовок є <object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.	-	<object>	"title": { "es": "Tu título", "en": "Your title" }
options	Масив варіантів для запитання. Кожен варіант може мати: "title" : Заголовок варіанту. Заголовок є <object>, що містить різні мови, дозволяючи показувати варіант обраною мовою під час потоку верифікації. "key": Ключ для варіанту, обраний клієнтом. Має залишатися унікальним у межах одного опитувальника.	-	<array>	"options": [ { "title": { "en": "Identity Document", "es": "Documento de identidad" }, "key": "identity-document" }, { "title": { "en": "Proof of Address", "es": "Comprobante de domicilio" }, "key": "proof-of-address" ]
mandatory	Вказує, чи потрібно обов'язково відповісти на запитання. Можливі значення: true, false	false	<boolean>	"mandatory": true
multiple	Вказує, чи запитання є одиничним чи множинним вибором. Можливі значення: true, false	false	<boolean>	"multiple": true
showConditions	Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.	-	<object>	"showConditions": { "questionKey": "question1", "answer": "option1" }

Розгорнути, щоб переглянути приклад запитання ВИПАДАЮЧИЙ СПИСОК

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

---

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

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

Параметр	Опис	За замовчуванням	Тип	Приклад
type	file	-	<string>	"type": "file"
key	Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії. Рекомендується використовувати ключ, що коротко описує запитання.	-	<string>	"key": "choose-from-list"
title	Заголовок є <object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.	-	<object>	"title": { "es": "Tu título", "en": "Your title" }
description	Опис, що з'являється під заголовком. Подібно до заголовка, опис може бути <object>, що містить різні мови, тож він може відображатися обраною мовою під час потоку верифікації.	-	<object>	"description": { "es": "Tu descripción", "en": "Your description" }
mandatory	Вказує, чи потрібно обов'язково відповісти на запитання. Можливі значення: true, false	false	<boolean>	"mandatory": true
fileTypes	Вказує типи файлів, які користувач може завантажувати. Можливі значення: pdf, image.	[ "pdf", "image" ]	<array>	"fileTypes": [ "pdf", "image" ]
filesMaxCount	Вказує максимальну кількість файлів, які користувач може завантажити. Можливі значення: Число від 1 до 10.	10	<number>	"filesMaxCount": 5
showConditions	Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.	-	<object>	"showConditions": { "questionKey": "question1", "answer": "option1" }

Розгорнути, щоб переглянути приклад запитання ЗАВАНТАЖЕННЯ ФАЙЛУ

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

---

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

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

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

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

Поведінка

• Вкладення видимі як оператору, так і кінцевому користувачу.

• Коли файли надані через API (answer) чи конфігурацію, вони з'являться при відкритті опитувальника.

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

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

Параметр	Опис	За замовчуванням	Тип	Приклад
type	attachment	-	<string>	"type": "attachment"
key	Ключі обираються клієнтом та мають залишатися унікальними в межах однієї сесії. Рекомендується використовувати ключ, що коротко описує запитання.	-	<string>	"key": "attached-documents"
title	Заголовок є <object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.	-	<object>	"title": { "es": "Tu título", "en": "Your title" }
description	Опис, що з'являється під заголовком. Подібно до заголовка, опис може бути <object>, що містить різні мови, тож він може відображатися обраною мовою під час потоку верифікації.	-	<object>	"description": { "es": "Tu descripción", "en": "Your description" }
fileTypes	Вказує типи файлів, які користувач може завантажувати. Можливі значення: pdf, image.	[ "pdf", "image" ]	<array>	"fileTypes": [ "pdf", "image" ]
filesMaxCount	Вказує максимальну кількість файлів, які користувач може завантажити. Можливі значення: Число від 1 до 10.	10	<number>	"filesMaxCount": 5
showConditions	Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.	-	<object>	"showConditions": { "questionKey": "question1", "answer": "option1" }
allowOperatorUpload	Контролює, як додаються файли: • true – оператор завантажує файли за сесією. • false – файли надаються лише через конфігурацію чи API.	true	<boolean>	"allowOperatorUpload": true
allowOperatorOverride	Якщо false, оператор не може редагувати вкладення після того, як користувач підтвердив опитувальник. Якщо true, оператор все ще може завантажувати або видаляти файли.	true	<boolean>	"allowOperatorOverride": true

Розгорнути, щоб переглянути приклад запитання ВКЛАДЕННЯ

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