KYC (Know Your Customer)

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

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

Flags (Прапорці)

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

Назва прапорця

Опис

За замовчуванням

Тип

skip_face

Пропускає крок liveness, якщо він вже існує у визначених кроках. Запобігає дублюванню при використанні власних потоків.

false

skip_document

Пропускає крок identity-document, якщо він вже існує у визначених кроках. Запобігає дублюванню при використанні власних потоків.

false

return_url

URL для перенаправлення користувача після завершення процесу ідентифікації. Якщо не вказано, вважається, що сесія вбудована в iframe.

null

language

Код мови інтерфейсу користувача. Підтримувані значення:

"es", "ka", "uk", "ru", "uz", "it", "gr", "tr", "ro", "ar", "de", "pl", "hi", "bn", "az", "ja", "pt", "fr", "kk", "sv"

"en"

skip_desktop

Обмежує сесії лише мобільними пристроями. Якщо ініційовано на комп'ютері, відображається QR-код для перенесення сесії на мобільний пристрій.

false

switch_device_url

Користувацький URL для відображення в QR-коді, якщо камера недоступна або заблокована. Якщо URL не вказано або поле залишено порожнім, QR-код не відображатиметься.

null

restrict_url_sharing

Забороняє використання URL-адреси сесії в іншому браузері або на іншому пристрої. Якщо встановлено true, QR-код не відображатиметься, коли доступ до камери заборонено, якщо не вказано switch_device_url.

false

requiredHdMedia

Вимагає використання камери Full HD (1080p+) для кроків liveness та identity-document. Якщо не виконано, показується QR-код для переходу користувача на інший пристрій.

false

Steps (Кроки)

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

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

Властивість

Опис

type

Тип конкретного кроку (див. список підтримуваних типів кроків нижче).

key

Унікальний ідентифікатор кроку. Цей ключ можна налаштувати, але він має залишатися унікальним у межах сесії.

flags

Прапорці конфігурації, специфічні для кроку, які контролюють поведінку цього кроку.

title

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

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

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

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

Identity document verification (Верифікація документа, що посвідчує особу)

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

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

Заголовок: ID verification
Тип: identity-document
Ключ: identity-document
Прапорці:
- disable_document_capture
- allow_document_upload
- document_types
- document_countries

Прапорець

Опис

За замовчуванням

Тип

disable_document_capture

Вимикає живе сканування документа. Користувачі можуть лише завантажувати зображення своїх документів.

false

allow_document_upload

Вмикає опцію сканувати або завантажувати документ.

false

allow_nfc_capture

Вмикає зчитування NFC-чипа для підтримуваних документів, що посвідчують особу (наприклад, біометричні паспорти та ID-картки). Коли увімкнено, користувачі можуть сканувати NFC-чип документа за допомогою сумісного пристрою.

false

document_types

Список дозволених типів документів.

Можливі значення:

"id", "passport", "driver_license", "residence_license"

Усі типи

Array<string>

document_countries

Обмежує прийнятних видавців документів конкретними кодами країн (наприклад, "USA", "DEU", "ITA").

Без обмежень

Array<string>

optional_continue_on_another_device

Дозволяє користувачам за бажанням перейти на інший пристрій, щоб продовжити сесію.

false

Приклад cURL:

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

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

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

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

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

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

Прапорець

Опис

За замовчуванням

Тип

check

Вмикає сторінку перевірки даних документа.

false

<boolean>

allowedUsers

Визначає, хто може редагувати витягнуті дані на сторінці перегляду. Можливі значення: "client" (кінцевий користувач, що проходить верифікацію), "operator" (оператор, який контролює сесію).

—

Array<string>

fields

Карта OCR-полів для включення на сторінку перегляду. Кожне поле можна налаштувати властивостями editable та mandatory.

—

Object

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

Прапорець

Опис

Тип

type

Тип даних поля. Можливі значення: "string", "datestring"

<string>

editable

Чи може користувач або оператор редагувати це поле.

<boolean>

mandatory

Чи має поле бути заповненим перед подачею.

<boolean>

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

Поле

Ключ

Компонент

Ім'я (англ.)

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

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

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

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

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

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

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

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

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

Заголовок: Liveness
Тип: liveness
Ключ: liveness
Прапорці:
- liveness
- allow_face_upload
- adaptive_liveness
- instructions

Прапорець

Опис

За замовчуванням

Тип

liveness

Визначає тип перевірки живості:

true: активна живість
false: пасивна живість

false

allow_face_upload

Дозволяє користувачеві завантажити селфі замість використання камери.

⚠️ Цей прапорець ігнорується, якщо liveness дорівнює true, оскільки активні перевірки вимагають живого вводу.

false

optional_continue_on_another_device

Дозволяє користувачам за бажанням перейти на інший пристрій, щоб продовжити сесію.

false

adaptive_liveness

(Лише SDK) Вмикає новий досвід Adaptive liveness із покращеним UI та виявленням. Має бути true, щоб використовувати Adaptive Liveness. ⚠️ Якщо adaptive_liveness дорівнює true, прапорець liveness має бути false.

false

instructions

Визначає дії, які користувач має виконати для Adaptive Liveness. Застосовується лише якщо adaptive_liveness дорівнює true. Наразі підтримувана опція: [ "smile" ].

[ "smile" ]

Array<string>

Приклад cURL:

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

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

curl https://widget.identomat.com/external-api/begin/ -d '{
    "company_key": "your_company_key_here",
    "flags": {
        "language": "en"
    },
    "steps": [
        {
            "title": {
                "en": "ID verification"
                },
            "type": "identity-document",
            "key": "select_document_id",
            "flags": {
                "allow_document_upload": true,
                "document_types": [
                    "id",
                    "passport",
                    "driver_license",
                    "residence_license"
                ],
                "document_countries": [
                    "USA",
                    "FRA"
                ]
            }
        },
        {
            "title": {
                "en": "Liveness check"
                },
            "type": "liveness",
            "key": "liveness",
            "flags": {
                "liveness": true
            }
        }
    ]
}'

Proof of Address (Підтвердження адреси)

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

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

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

Прапорець

Опис

За замовчуванням

Тип

general_document_types

Список дозволених типів документів. Якщо не вказано або встановлено порожній масив, для завантаження будуть доступні всі типи документів.

Можливі значення:

"bank_statement", "utility_bill", "yellow_slip", "drivers_license", "vehicle_registration_certificate"

Усі типи

<array>

Приклад cURL:

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

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

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

Selfie with ID (Селфі з документом)

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

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

Заголовок: Selfie with ID
Тип: face-document
Ключ: capture_face_document
Прапорці:
- allow_face_doc_upload
- require_face_document

Прапорець

Опис

За замовчуванням

Тип

allow_face_doc_upload

Дозволяє користувачам завантажити зображення себе з документом.

false

require_face_document

Вимагає, щоб користувачі зробили живий знімок себе з документом.

false

optional_continue_on_another_device

Дозволяє користувачам за бажанням перейти на інший пристрій, щоб продовжити сесію.

false

Приклад cURL:

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

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

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

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 (необов'язково)

Прапорець

Опис

За замовчуванням

Тип

steps

Список кроків для виконання під час відеодзвінка (крім language та operator_questionnaire).

[ ]

<array>

resetSteps

Якщо true, дані верифікації користувача скидаються, коли він повторно приєднується до дзвінка.

false

hideCameraOption

Увімкнення цього приховає іконку камери, забороняючи користувачам вимикати камеру.

false

nameRequired

Вимагає, щоб користувачі ввели своє ім'я перед приєднанням.

false

multiple_participants

Вмикає багатокористувацькі відеосесії.

false

Приклад cURL:

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

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

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

Phone number (Номер телефону)

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

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

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

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

Тип: phone-number
Ключ: phone_number
Прапорці:
- require_phone_number_check
- require_phone_number

Прапорець

Опис

За замовчуванням

Тип

require_phone_number_check

Вимагає, щоб користувачі перевірили свій номер за допомогою коду OTP.

false

require_phone_number

Вимагає, щоб користувачі надали номер телефону без перевірки.

false

Приклад cURL:

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

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

curl https://widget.identomat.com/external-api/begin/ -d '{
"company_key": "your_company_key_here",
"flags": {
        "return_url": "https://example.com/",
        "language": "it"
},
"steps": [
    {
        "title": {
            "it": "Phone number verification"
            },
        "type": "phone-number",
        "key": "phone_number",
        "flags": {
            "require_phone_number_check": true
        }
    }
]
}'

Email

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

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

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

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

Тип: email
Ключ: require_email
Прапорці:
- require_email_check
- require_email

Прапорець

Опис

За замовчуванням

Тип

require_email_check

Вимагає верифікації email за допомогою коду OTP.

false

require_email

Вимагає, щоб користувачі надали email без перевірки.

false

Приклад cURL:

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

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

curl https://widget.identomat.com/external-api/begin/ -d '{
"company_key": "your_company_key_here",
"flags": {
        "return_url": "https://example.com/",
        "language": "en"
},
"steps": [
    {
        "title": {
            "en": "Email verification"
            },
        "type": "email",
        "key": "require_email",
        "flags": {
            "require_email_check": true
        }
    }
]
}'

Geolocation (Геолокація)

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

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

Тип: geolocation
Ключ: require_geolocation
Прапорці:
- require_geolocation

Прапорець

Опис

За замовчуванням

Тип

require_geolocation

Вимагає доступу до місцезнаходження для проходження кроку.

true

Приклад cURL:

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

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

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

AnyDoc reader

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

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

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

Параметр

Опис

За замовчуванням

Тип

documentType

Довільна текстова мітка, що ідентифікує тип документа (наприклад, «Payslip», «Bank Statement»). Використовується внутрішньо в деталях сесії та виводі API. Обов'язково.

allowedFormats

Формати файлів, прийняті для завантаження. Можливі значення: "pdf", "image"

Усі типи

Array<string>

pageConfiguration

Чи очікується, що документ буде однією чи декількома сторінками. Можливі значення: "single", "multiple"

"single"

pageCount

Очікувана кількість сторінок, використовується лише коли pageConfiguration дорівнює "multiple". Якщо не вказано, обробляються всі завантажені сторінки.

null

documentValidity

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

{ "enabled": false }

language

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

Автовизначення

extractionHint

Додатковий контекст про документ загалом, наданий ШІ разом із підказками на рівні полів. Рекомендується англійською мовою незалежно від мови документа.

null

confidenceThreshold

Мінімальний бал достовірності (0–100), необхідний для прийняття витягнутого поля без позначення. Застосовується до всіх полів, якщо не перевизначено для окремого поля.

80

retryLimit

Максимальна кількість разів, коли користувач може завантажити чи зняти документ на цьому кроці.

3

fields

Масив об'єктів полів, що визначають дані для витягування. Див. деталі нижче.

Array<object>

Об'єкт documentValidity:

Властивість

Опис

За замовчуванням

Тип

enabled

Вмикає або вимикає перевірку чинності.

false

dateField

key поля (має бути типу date), витягнуте значення якого перевіряється проти maxAge. Обов'язково, коли enabled дорівнює true.

maxAge

Максимальний дозволений вік документа, у вигляді пари value + unit. Можливі значення unit: "days", "weeks", "months", "years".

Fields (Поля)

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

Параметр

Опис

За замовчуванням

Тип

key

Унікальний ідентифікатор поля в межах кроку. Використовується для посилання на витягнуте значення у виводі API. Обов'язково.

type

Визначає, як перевіряється та форматується витягнуте значення. Можливі значення: "text", "number", "date", "boolean", "email", "phone", "currency", "money", "iban" "taxId", "address", "percentage", "other"

otherTypeLabel

Довільний текстовий опис даних, які містить це поле. Використовується лише коли type дорівнює "other"; якщо залишити порожнім, ШІ розглядає поле як вільний текст без перевірки формату.

null

label

Назва поля для відображення, використовується для ідентифікації в документі та показується в деталях сесії. Необов'язкова, якщо надано extractionHint.

alternativeNames

Альтернативні терміни через кому, під якими це поле може з'являтися в документі (наприклад, «Sex, Male/Female» для поля Gender). Використовується лише для інформування витягування, не показується в перегляді чи виводі API.

null

mandatory

Чи позначається сесія, якщо це поле не може бути витягнуте.

false

confidenceThreshold

Перевизначає поріг достовірності на рівні кроку для цього конкретного поля.

Успадковує значення за замовчуванням кроку

extractionHint

Додатковий контекст про це поле, наданий ШІ при витягуванні його значення. Рекомендується англійською мовою незалежно від мови документа. Необов'язково, якщо надано label.

null

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

Приклад cURL:

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

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

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

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

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

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

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

Приклад cURL:

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

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

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

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

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

Рекомендується використовувати ключ, що коротко описує опитувальник.

"key": "terms-and-conditions"

title

Заголовок опитувальника користувача, показаний як заголовок блоку з боку користувача. Заголовок може бути <object>, що містить різні мови, дозволяючи показувати заголовок обраною мовою під час потоку верифікації.

"title": { 
    "es": "Tu título",
    "en": "Your title"
}

description

Опис, що з'являється під заголовком з боку користувача. Подібно до заголовка, опис може бути <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

"mandatory": false

answer

Дозволяє попередньо встановити відповідь на запитання.

"answer": "option2"

readOnly

Показує запитання, але обмежує взаємодію.

false

"readOnly": false

showConditions

Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.

"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }

successButtonTitle

Заголовок кнопки дії в опитувальнику. Якщо запитання є обов'язковими, кнопка деактивується, доки користувач не завершить опитувальник.

Confirm

"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

"type": "string"

key

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

Рекомендується використовувати ключ, що коротко описує запитання.

"key": "your-address"

title

Заголовок є <object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.

"title": { 
    "es": "Tu título",
    "en": "Your title"
}

format

Визначає очікувану структуру відповіді користувача. Визначає, як перевіряється ввід.

free-text

"format": {
    "type": "free-text"
}

"format": {
    "type": "email"
}

"format": {
    "type": "contactNumber"
}

mandatory

Вказує, чи потрібно обов'язково відповісти на запитання.

Можливі значення:

true, false

false

"mandatory": true

answer

Дозволяє попередньо встановити відповідь на запитання. Відповідь є <object> мов, тож якщо користувач змінює мову під час потоку верифікації, попередньо заповнену відповідь можна показувати різними мовами.

"answer": { 
        "en": "This is a prefilled answer",
        "es":"Esta es una respuesta prellenada."
}

readOnly

Показує запитання, але обмежує взаємодію.

false

"readOnly": true

showConditions

Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.

"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }

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

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

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

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

Параметр

Опис

За замовчуванням

Тип

Приклад

type

multiple-choice

"type": "multiple-choice"

key

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

Рекомендується використовувати ключ, що коротко описує запитання.

"key": "check-two-answers"

title

"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

"mandatory": true

answer

Дозволяє попередньо встановити відповідь на запитання. Відповідь являє собою масив (array) ключів варіантів відповіді, визначених для цього запитання.

<array>

"answer": [
    "option-1",
    "option-2"
]

readOnly

Показує запитання, але обмежує взаємодію.

false

"readOnly": true

showConditions

Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.

"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

"type": "options"

key

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

Рекомендується використовувати ключ, що коротко описує запитання.

"key": "choose-one-answer"

title

"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

"mandatory": true

answer

Дозволяє попередньо встановити відповідь на запитання. Відповідь є <string> ключа варіанту, призначеного для цього запитання.

"answer": "option-1"

readOnly

Показує запитання, але обмежує взаємодію.

false

"readOnly": true

showConditions

Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.

"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

"type": "dropdown"

key

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

Рекомендується використовувати ключ, що коротко описує запитання.

"key": "choose-from-list"

title

"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

"mandatory": true

multiple

Вказує, чи запитання є одиничним чи множинним вибором.

Можливі значення:

true, false

false

"multiple": true

showConditions

Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.

"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

"type": "file"

key

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

Рекомендується використовувати ключ, що коротко описує запитання.

"key": "choose-from-list"

title

Заголовок є <object> мов, тож якщо користувач змінює мову під час потоку верифікації, запитання можна показувати різними мовами. Немає обмежень щодо довжини чи символів.

"title": { 
    "es": "Tu título",
    "en": "Your title"
}

description

Опис, що з'являється під заголовком. Подібно до заголовка, опис може бути <object>, що містить різні мови, тож він може відображатися обраною мовою під час потоку верифікації.

"description": {
    "es": "Tu descripción",
    "en": "Your description"
}

mandatory

Вказує, чи потрібно обов'язково відповісти на запитання.

Можливі значення:

true, false

false

"mandatory": true

fileTypes

Вказує типи файлів, які користувач може завантажувати. Можливі значення: pdf, image.

[ "pdf", "image" ]

<array>

"fileTypes": [
    "pdf",
    "image"
]

filesMaxCount

Вказує максимальну кількість файлів, які користувач може завантажити. Можливі значення: Число від 1 до 10.

"filesMaxCount": 5

showConditions

Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.

"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 дозволяє прикріпляти файли до опитувальника. Він підтримує два основних випадки використання:

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

Поведінка

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

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

Параметр

Опис

За замовчуванням

Тип

Приклад

type

attachment

"type": "attachment"

key

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

Рекомендується використовувати ключ, що коротко описує запитання.

"key": "attached-documents"

title

"title": { 
    "es": "Tu título",
    "en": "Your title"
}

description

"description": {
    "es": "Tu descripción",
    "en": "Your description"
}

fileTypes

Вказує типи файлів, які користувач може завантажувати. Можливі значення: pdf, image.

[ "pdf", "image" ]

<array>

"fileTypes": [
    "pdf",
    "image"
]

filesMaxCount

Вказує максимальну кількість файлів, які користувач може завантажити. Можливі значення: Число від 1 до 10.

"filesMaxCount": 5

showConditions

Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.

"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }

allowOperatorUpload

Контролює, як додаються файли: • true – оператор завантажує файли за сесією. • false – файли надаються лише через конфігурацію чи API.

true

"allowOperatorUpload": true

allowOperatorOverride

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

true

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

Operator questionnaire (Опитувальник оператора)

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

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

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

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

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

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

Options (Варіанти)

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

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

{
  "en": "ID card"
}

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

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

Параметр

Опис

За замовчуванням

Тип

Приклад

key

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

Рекомендується використовувати ключ, що коротко описує опитувальник.

"key": "document-collection"

title

Заголовок опитувальника оператора, показаний як назва вкладки в сесії. Заголовок може бути <object>, що містить різні мови, дозволяючи показувати заголовок обраною мовою.

"title": { 
    "es": "Tu título",
    "en": "Your title"
}

description

Подібно до заголовка, опис може бути <object>, що містить різні мови, тож він може відображатися обраною мовою.

"description": {
    "es": "Tu descripción",
    "en": "Your description"
}

questions

Масив запитань наступних типів: string, multiple-choice та options.

<array>

"questions": [
    {
    "type": "string",
    "title": "Your title",
    "key": "question1",
    "mandatory": true
    },
    {
    "type": "multiple-choice",
    "title": "Your title",
    "key": "question2",
    "mandatory": false,
    "options": [
        {
        "title": "Your title",
        "key": "option1"
        },
        { 
        "title": "Your title",
        "key": "option2"
        }
    ]
    }
]

mandatory

Вказує, чи потрібно обов'язково відповісти на запитання.

Можливі значення:

true, false

false

"mandatory": false

answer

Дозволяє попередньо встановити відповідь на запитання.

"answer": "option2"

readOnly

Показує запитання, але обмежує взаємодію.

false

"readOnly": false

showConditions

Цей параметр можна використати, щоб встановити умови для того, чи має запитання відображатися.

"showConditions": {
    "questionKey": "question1",
    "answer": "option1"
    }

Приклад cURL:

Розгорнути, щоб переглянути приклад operator-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": "operator-questionnaire",
            "title": {
                "es": "Tu título",
                "en": "Your title"
            },
            "description": {
                "es": "Tu descripción",
                "en": "Your description"
            },
            "questions": [
                {
                    "type": "string",
                    "title": {
                        "es": "Tu título",
                        "en": "Your title"
                    },
                    "key": "question1",
                    "mandatory": true
                },
                {
                    "type": "multiple-choice",
                    "title": {
                        "es": "Tu título",
                        "en": "Your title"
                    },
                    "key": "question2",
                    "mandatory": false,
                    "options": [
                        {
                            "title": {
                                "es": "Tu título",
                                "en": "Your title"
                            },
                            "key": "option1"
                        },
                        {
                            "title": {
                                "es": "Tu título",
                                "en": "Your title"
                            },
                            "key": "option2"
                        }
                    ],
                    "answer": [
                        "option2"
                    ],
                    "readOnly": true
                },
                {
                    "type": "options",
                    "title": {
                        "es": "Tu título",
                        "en": "Your title"
                    },
                    "key": "question3",
                    "mandatory": true,
                    "options": [
                        {
                            "title": {
                                "es": "Tu título",
                                "en": "Your title"
                            },
                            "key": "option3"
                        },
                        {
                            "title": {
                                "es": "Tu título",
                                "en": "Your title"
                            },
                            "key": "option4"
                        }
                    ]
                }
            ]
        }
    ]
}'

Additional session parameters (Додаткові параметри сесії)

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

Назва параметра

Опис

За замовчуванням

Тип

name

Користувацька мітка сесії, показана в панелі керування до завершення верифікації користувачем. Після завершення сесії це значення замінюється іменем верифікованого користувача (якщо доступне).

null

clientUserId

Унікальний ідентифікатор, що використовується для зв'язку сесії з конкретним користувачем у вашій системі. Корисно для групування сесій чи синхронізації з внутрішніми ID користувачів чи облікових записів.

null

groupId

Визначає групу, призначену для сесії. Наприклад, під час відеодзвінка лише учасники цієї вказаної групи зможуть отримати дзвінок.

null

scheduleStartTime

Дата та час, коли сесія стає доступною кінцевому користувачу. До цього часу сесію неможливо розпочати. Формат: ISO 8601 — наприклад, "2024-06-20T07:33:00.000Z"

null

<string> (ISO 8601 datetime)

scheduleEndTime

Дата та час, після якого сесія більше недоступна кінцевому користувачу. Формат: ISO 8601 — наприклад, "2024-06-20T09:00:00.000Z"

null

<string> (ISO 8601 datetime)

Приклад:

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

PreviousПосібник для розробників

NextKYB (Know Your Business)

Last updated 17 days ago

Was this helpful?