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

# Довідник API

### Ліміт запитів

Для захисту стабільності системи та запобігання зловживанням наш API застосовує обмеження швидкості запитів:

* **Ліміт**: Максимум **600 запитів за хвилину** з однієї IP-адреси.
* **Перевищення ліміту**: Якщо IP-адреса перевищує цей поріг, вона буде **тимчасово заблокована на 1 годину**.
* **Відповідь про помилку**: Протягом періоду блокування всі запити з заблокованої IP-адреси повертатимуть помилку **`529 Too many requests`**.

***

### Керування сесіями

Використовуйте ці ендпоінти для створення сесій верифікації та керування ними. Сесії можна запускати за допомогою збереженої конфігурації (рекомендовано) або з власними кроками та прапорцями.

<details>

<summary>begin/ - Створення сесії (застаріле)</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/begin/</mark>](https://widget.identomat.com/external-api/begin/)

**Опис:**

Ініціює нову сесію верифікації. Сесії можна запускати або за допомогою попередньо визначеної конфігурації (`config_id`), або явно вказавши кроки та прапорці для власного потоку.

Цей ендпоінт тепер також підтримує **перевизначення окремих кроків у межах конфігурації**. Це дозволяє вводити динамічні дані (наприклад, попередньо заповнювати дані користувача, як-от ім'я та прізвище), продовжуючи використовувати вашу збережену конфігурацію, роблячи перехід до налаштувань на основі конфігурацій більш гнучким.

**Параметри:**

* `company_key` *(string, обов'язковий)*- Секретний ключ компанії.
* `parent_session_id` *(string, необов'язковий)* – Вказує ID батьківської сесії при створенні дочірньої сесії для верифікації з декількома учасниками.

разом з:

* `config_id` (string, необов'язковий) - Унікальний ідентифікатор конфігурації сесії.

або:

* `flags` *(object, необов'язковий)* – Об'єкт JSON, що містить опції налаштування сесії.
* `steps` *(array, необов'язковий)* – Визначає послідовність кроків у процесі ідентифікації.

{% hint style="warning" %}
Використовуйте власні кроки та прапорці лише якщо у вас є дуже специфічні потреби, які неможливо задовольнити за допомогою конфігурацій. Із часом **ми рекомендуємо переносити всі власні потоки на конфігурації.**<br>

**Чому конфігурації важливі:**

* **Спрощує створення сесії** — не потрібно вручну визначати кроки та прапорці.
* **Зменшує ризик помилок** у потоці верифікації.
* **Захищено від застарівання** — застаріла обробка власних кроків з часом буде припинена.
* Дозволяє Identomat ефективно **підтримувати**, **покращувати** та **оптимізувати потоки**.
* Полегшує **інтеграцію**.
  {% endhint %}

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

```bash
curl https://widget.identomat.com/external-api/begin/ \
    -F 'company_key=your-company-secret-key' \
    -F 'config_id=62412c096c4b39ba845d4bf2'
```

Перегляньте всі приклади **кроків** у [Посібнику для розробників.](/identomat-documentation-ukr/posibnik-dlya-rozrobnikiv/kyc-know-your-customer.md)

**Приклади параметрів запиту:**

*Запустити сесію за замовчуванням:*

```json
{
  "company_key": "your-company-secret-key"
}
```

*Запустити сесію з конфігурацією **(рекомендовано)**:*

```json
{
  "company_key": "your-company-secret-key",
  "config_id": "62412c096c4b39ba845d4bf2"
}
```

*Запустити сесію з прапорцями та кроками:*

```json
{
  "company_key": "your-company-secret-key",
  "flags": {},
  "steps": [],
  "parent_session_id": "98aryxvvzwpi4zuasth332ozfucli3l0qx13hisc"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
"47fjzxvvzapi4ztasth3c2ozfucli3l0qx13hisc"
```

***

**Поведінка перевизначення конфігурації**

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

Підтримуються **два типи перевизначення**:

**1. Перевизначення кроків конфігурації**

Ви можете перевизначити один або декілька кроків із конфігурації, передавши масив `steps` у запиті `/begin`.

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

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

Це зазвичай використовується для:

* Попереднього заповнення відповідей опитувальника (наприклад, ім'я, згода)
* Динамічного коригування вмісту кроку
* Введення даних, специфічних для користувача, у попередньо визначені потоки

> Якщо надано і `config_id`, і `steps`, конфігурація використовується як основа, і **перевизначаються лише відповідні кроки**.

*Приклад:*

{% code expandable="true" %}

```json
{
    "company_key": "your-company-secret-key",
    "config_id": "62412c096c4b39ba845d4bf2",
    "steps": [
        {
            "type": "user-questionnaire",
            "key": "agreement",
            "title": {
                "en": "Personal information"
            },
            "questions": [
                {
                    "mandatory": true,
                    "type": "string",
                    "key": "agreement-1",
                    "title": {
                        "en": "Your full name"
                    },
                    "answer": "John Doe"
                }
            ],
            "successButtonTitle": {
                "en": "Continue"
            }
        }
    ]
}
```

{% endcode %}

**2. Перевизначення параметрів конфігурації (загальні)**

Ви можете перевизначити параметри рівня конфігурації, передавши їх через об'єкт `general` у запиті `/begin`.

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

Приклади параметрів, які можна перевизначити, включають:\
*(Див.* [*Налаштування конфігурації* ](/identomat-documentation-ukr/bezkodovii-konstruktor-robochikh-procesiv/nalashtuvannya-konfiguraciyi.md)*для повного списку та детальних описів усіх доступних параметрів)*

```json
{
  "language": "en",                                //Мова за замовчуванням
  "returnUrl": "https://www.identomat.com/",       //Return URL
  "optionalContinueOnAnotherDevice": false,        //Дозволити користувачу продовжити на іншому пристрої
  "restrictUrlSharing": false,                     //Обмежити поширення URL
  "switchDeviceUrl": "https://www.identomat.com/", //Передати користувацький QR URL 
  "skipDesktop": false,                            //Примусово перевести користувача на мобільний пристрій
  "useSmsNotifications": false,                    //Увімкнути SMS-сповіщення 
  "sessionLifetime": "15",                         //Тривалість сесії (хвилини)
  "identifyPersonWithFace": false,                 //Повторне розпізнавання обличчя 
  "checkScreening": true,                          //Скринінг 
  "minScreeningScore": "85",                       //Мінімальний бал скринінгу
  "screeningDatasets": ["default"],                //Набори даних для скринінгу
  "runScreeningAfter": "completion",               //Коли запускати скринінг
  "groups": ["667eb394d3ae73e1902da6dd"],          //Групи з доступом
  "requiredHdMedia": false                         //Вимагати FHD-камеру
}
```

Приклад запиту з використанням перевизначення параметрів:

```json
{
  "company_key": "your-company-secret-key",
  "config_id": "62412c096c4b39ba845d4bf2",
  "general": {
    "language": "ka",
    "useSmsNotifications": true,
    "sessionLifetime": "20"
  }
}
```

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

</details>

<details>

<summary>begin/ - Створення сесії (нове, з підтримкою запиту додаткової інформації)</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/begin</mark>](https://external-api.identomat.com/begin)

**Опис:**

Створює нову сесію верифікації за допомогою External API. На відміну від застарілого ендпоінту, цей ендпоінт використовує назви параметрів у форматі **camelCase** та підтримує конфігурації з увімкненим [**Запитом додаткової інформації**.](/identomat-documentation-ukr/koncepciyi-platformi/zapiti-dodatkovoyi-informaciyi.md)

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

> Для нових інтеграцій цей ендпоінт рекомендовано замість застарілого ендпоінту `begin/`.

**Параметри:**

* `companyKey` *(string, обов'язковий)* – Секретний ключ компанії.
* `configId` *(string, необов'язковий)* – Унікальний ідентифікатор конфігурації сесії.
* `parentSessionId` *(string, необов'язковий)* – Вказує ID батьківської сесії при створенні дочірньої сесії для верифікації з декількома учасниками.
* `name` *(string, необов'язковий)* – Користувацька назва сесії.
* `scheduleStartTime` *(string, необов'язковий, ISO 8601)* – Запланований час початку сесії.
* `scheduleEndTime` *(string, необов'язковий, ISO 8601)* – Запланований час завершення сесії.
* `groupId` *(string, необов'язковий)* – Призначає сесію конкретній групі.
* `createdByUser` *(string, необов'язковий)* – ID користувача, що створює сесію.
* `clientUserId` *(string, необов'язковий)* – Користувацький ідентифікатор заявника з вашого боку, корисний для зв'язування сесій із вашими внутрішніми записами користувачів.
* `general` *(object, необов'язковий)* – Перевизначає параметри рівня конфігурації лише для цієї сесії. Див. [Налаштування конфігурації](/identomat-documentation-ukr/bezkodovii-konstruktor-robochikh-procesiv/nalashtuvannya-konfiguraciyi.md) для повного списку доступних параметрів.
* `flags` *(object, необов'язковий)* – Об'єкт JSON, що містить опції налаштування сесії.
* `steps` *(array, необов'язковий)* – Визначає або перевизначає послідовність кроків у потоці верифікації. Якщо використовується разом із `configId`, перевизначаються лише відповідні кроки.

Перегляньте всі приклади **кроків** у [Посібнику для розробників.](broken://pages/SVzyVTrIH54UIFRTRiDo)

{% hint style="warning" %}
Використовуйте власні кроки та прапорці лише якщо у вас є дуже специфічні потреби, які неможливо задовольнити за допомогою конфігурацій. Із часом **ми рекомендуємо переносити всі власні потоки на конфігурації.**<br>

**Чому конфігурації важливі:**

* **Спрощує створення сесії** — не потрібно вручну визначати кроки та прапорці.
* **Зменшує ризик помилок** у потоці верифікації.
* **Захищено від застарівання** — застаріла обробка власних кроків з часом буде припинена.
* Дозволяє Identomat ефективно **підтримувати**, **покращувати** та **оптимізувати потоки**.
* Полегшує **інтеграцію**.
  {% endhint %}

***

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

```bash
curl -X POST https://external-api.identomat.com/begin \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "configId": "62412c096c4b39ba845d4bf2"
    }'
```

***

**Приклади параметрів запиту:**

*Створити стандартну сесію:*

```json
{
  "companyKey": "your-company-secret-key",
  "configId": "62412c096c4b39ba845d4bf2"
}
```

*Створити сесію з запитом додаткової інформації:*

```json
{
  "companyKey": "your-company-secret-key",
  "configId": "62412c096c4b39ba845d4bf2"
}
```

*Запросити додаткову інформацію для наявної сесії:*

```json
{
  "companyKey": "your-company-secret-key",
  "configId": "62412c096c4b39ba845d4bf2",
  "sessionId": "parent-session-id"
}
```

Коли надано `sessionId`, батьківська сесія залишається незмінною. **Створюється лише нова дочірня сесія** зі свіжим URL для заявника. Завжди діліться найновішим `additionalSessionUrl` із заявником.

***

**Приклади результату:**

*Стандартна конфігурація:*

```json
{
  "id": "session-id",
  "url": "https://widget.identomat.com/?session_token=session-id"
}
```

*Конфігурація з увімкненим `additionalInformationRequest`:*

```json
{
  "id": "parent-session-id",
  "url": "https://widget.identomat.com/?session_token=child-session-id",
  "additionalSessionId": "child-session-id",
  "additionalSessionUrl": "https://widget.identomat.com/?session_token=child-session-id"
}
```

***

**Поля відповіді:**

<table><thead><tr><th width="199.55859375">Поле</th><th>Опис</th></tr></thead><tbody><tr><td><code>id</code></td><td>ID батьківської сесії. Використовуйте це, щоб відстежувати сесію в Manage та отримувати колбеки.</td></tr><tr><td><code>url</code></td><td>URL для заявника дочірньої сесії. Дублює <code>additionalSessionUrl</code> для зворотної сумісності.</td></tr><tr><td><code>additionalSessionId</code></td><td>ID дочірньої сесії. Присутнє лише коли `additionalInformationRequest` увімкнено в конфігурації.</td></tr><tr><td><code>additionalSessionUrl</code></td><td>URL для заявника дочірньої сесії. Присутнє лише коли `additionalInformationRequest` увімкнено в конфігурації.</td></tr></tbody></table>

</details>

<details>

<summary>result/ - Результат сесії <strong>KYC (клієнта)</strong></summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/result/</mark>](https://widget.identomat.com/external-api/result/)

\
**Опис:**

Цей ендпоінт дозволяє отримати результат сесії верифікації. На основі ID сесії, відповідь поверне остаточне рішення (approved/rejected), дані документа, витягнуту інформацію та метадані.

**Параметри:**

* `company_key` *(string, обов'язковий)* - Секретний ключ компанії.
* `session_token` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

```bash
 curl https://widget.identomat.com/external-api/result/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'session_token={example-session-id-12345}'
```

**Приклади параметрів запиту:**

```json
{
  "company_key": "your-company-secret-key",
  "session_token": "example-session-id-12345"
}
```

***

**📹 videoCallStatus:**

Якщо сесія включала **крок відеодзвінка**, ендпоінт `/result` включатиме масив `videoCallStatus`.\
Це дозволяє клієнтам відстежувати життєвий цикл кожної кімнати відеодзвінка — коли її було створено, коли вона завершилась, і коли складене відеофайл стає доступним.

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

```json
"videoCallStatus": [
  {
    "roomId": "RM27b1b047ccc30c0519959d66b4f0689d",
    "roomStatus": "ended",
    "compositionStatus": "available",
    "videoFileStatus": "available",
    "videoFileId": "hlwXVfonxNogXujgqT9anl1EphgwNiXuy7ug96sH"
  }
]
```

**Структура об'єкта:**

Кожен запис у `videoCallStatus` дотримується такої схеми:

```json
{
  "roomId": "string",
  "roomStatus": "created | ended | empty",
  "compositionStatus": "null | started | available",
  "videoFileStatus": "null | started | available",
  "videoFileId": "null | string"
}
```

**Опис статусів:**

<table><thead><tr><th width="169.7734375">Поле</th><th width="133.3046875">Можливі значення</th><th>Значення</th></tr></thead><tbody><tr><td><strong>roomStatus</strong></td><td><code>created</code></td><td>Кімнату успішно створено; дзвінок триває.</td></tr><tr><td></td><td><code>ended</code></td><td>Оператор завершив дзвінок.</td></tr><tr><td></td><td><code>empty</code></td><td>Кімната відеодзвінка завершилась без запису медіа.</td></tr><tr><td><strong>compositionStatus</strong></td><td><code>null</code></td><td>Композицію ще не розпочато.</td></tr><tr><td></td><td><code>started</code></td><td>Композицію (об'єднання відео) розпочато.</td></tr><tr><td></td><td><code>available</code></td><td>Складене повне відео готове.</td></tr><tr><td><strong>videoFileStatus</strong></td><td><code>null</code></td><td>Фінальний відеофайл ще не згенеровано.</td></tr><tr><td></td><td><code>started</code></td><td>Генерацію відеофайлу розпочато.</td></tr><tr><td></td><td><code>available</code></td><td>Фінальний завантажуваний відеофайл готовий.</td></tr><tr><td><strong>videoFileId</strong></td><td><code>null</code> або ID файлу</td><td>Якщо доступно, цей ID можна використати для завантаження складеного відео.</td></tr></tbody></table>

***

**Приклади результату:**

*<mark style="color:green;">sessionApproved:</mark>*

{% code expandable="true" %}

```json
{
    "result": "approved",
    "similarity": 0.9027283530404249,
    "live": false,
    "document_type": "id",
    "generalDocuments": [
        {
            "pages": [
                {
                    "typeId": "utility-bill",
                    "final": {
                        "street": "Main Street",
                        "state": "California",
                        "city": "Los Angeles",
                        "country": "United States",
                        "postalCode": "90001",
                        "streetNumber": "123",
                        "county": "Los Angeles County",
                        "countryCode": "USA",
                        "documentIssued": "1/15/2025",
                        "documentIssuedTime": "2025-01-15T00:00:00",
                        "authority": "Bank of America, NA",
                        "address": "123 Main St, Los Angeles, CA 90001",
                        "formattedAddress": "123 Main St, Los Angeles, CA 90001, USA",
                        "latitude": 34.052235,
                        "longitude": -118.243683,
                        "fullName": "John Doe",
                        "firstName": "John",
                        "lastName": "Doe",
                        "permanent": null
                    },
                    "documentPages": [
                        {
                            "pageNumber": 1
                        }
                    ],
                    "pageNumber": 1,
                    "statuses": []
                }
            ],
            "documentType": "UTILITY_BILL",
            "permanent": null,
            "typeId": "utility_bill"
        }
    ],
    "reject_reason": {
        "value": "",
        "description": ""
    },
    "result_comment": "",
    "name": "John Doe",
    "face_images": 1,
    "id_card_front": {
        "Given_Names_en_US": "John",
        "Surname_en_US": "Doe",
        "citizenship": "USA",
        "Sex_en_US": "M",
        "Personal_Number_en_US": "123456789",
        "Date_of_Birth_en_US": "1/8/1980",
        "Date_of_Expiry_en_US": "8/9/2025",
        "Document_Number_en_US": "AB1234567",
        "Issuing_State_Code_en_US": "USA",
        "Date_of_Birth_ISO": "1980-01-08T00:00:00.000Z",
        "Date_of_Expiry_ISO": "2025-08-09T00:00:00.000Z"
    },
    "id_card_back": {
        "Date_of_Issue_en_US": "6/28/2021",
        "Issuing_State_Code_en_US": "USA",
        "Place_of_Birth_en_US": "USA",
        "Date_of_Issued_ISO": "2021-06-28T00:00:00.000Z",
        "Given_Names_en_US": "John",
        "Surname_en_US": "Doe",
        "Nationality_Code_en_US": "USA",
        "Sex_en_US": "M",
        "Personal_Number_en_US": "123456789",
        "Date_of_Birth_en_US": "1/8/1980",
        "Date_of_Expiry_en_US": "6/28/2028",
        "Document_Number_en_US": "AB0002261",
        "Nationality_en_US": "USA",
        "Date_of_Birth_ISO": "1980-01-08T00:00:00.000Z",
        "Date_of_Expiry_ISO": "2028-06-28T00:00:00.000Z",
        "mrz": "IDUSAAB0002261938001085718<<<<\n8001081M2806288USA<<<<<<<<<<<1\nDOE<<JOHN<<<<<<<<<<<<<<<<<<<"
    },
    "suggested": {},
    "person": {
        "email": "johndoe@email.com",
        "phoneNumber": "+1234567890",
        "first_name": "John",
        "last_name": "Doe",
        "birthday": "1/8/1980",
        "birthday_time": "1980-01-08T00:00:00.000Z",
        "age": 45,
        "citizenship": "USA",
        "document_number": "AB0002261",
        "document_expires": "6/28/2028",
        "document_expires_time": "2028-06-28T00:00:00.000Z",
        "personal_number": "123456789",
        "issuing_state": "USA",
        "sex": "M",
        "birth_place": "USA",
        "nationality": "USA",
        "document_issued": "6/28/2021",
        "document_issued_time": "2021-06-28T00:00:00.000Z",
        "status": "FIELDS_MATCH",
        "mrz": "IDUSAAB0002261938001085718<<<<\n8001081M2806288USA<<<<<<<<<<<1\nDOE<<JOHN<<<<<<<<<<<<<<<<<<<",
        "address": "2804 Fairway Dr, Cedar Hill, TX 75104, USA"
    },
    "questionnaires": [
        {
            "key": "agreement",
            "questions": [
                {
                    "key": "question1",
                    "answer": "John Doe"
                },
                {
                    "key": "question2",
                    "answer": "option4"
                },
                {
                    "key": "question3",
                    "answer": [
                        "option1",
                        "option2"
                    ]
                },
                {
                    "key": "question5",
                    "answer": 1
                },
                {
                    "key": "question6",
                    "answer": "readOnly answer"
                }
            ]
        }
    ],
    "geolocation": [
        {
            "key": "require_geolocation",
            "latitude": 34.05221168293059,
            "longitude": -118.24393094417908,
            "address": "123 Main St, Los Angeles, CA 90001, USA"
        }
    ],
    "technicalDetails": {
        "remoteAddress": "192.168.1.1",
        "userAgent": "PostmanRuntime/7.37.3",
        "countryCode": "US"
    },
    "videoCallStatus": [
        {
            "roomId": "RMf12391ce20597708d747587bdee8e715",
            "roomStatus": "ended",
            "compositionStatus": "available",
            "videoFileStatus": "available",
            "videoFileId": "av7YsrnDopwVmyzLtzkPKSiyWKVIaQDQZPtDfEq0"
        },
        {
            "roomId": "RM48170f8ee1235e27d5d09f8330b4f67f",
            "roomStatus": "empty",
            "compositionStatus": null,
            "videoFileStatus": null,
            "videoFileId": null
        }
    ]
}
```

{% endcode %}

*<mark style="color:red;">sessionRejected:</mark>*

{% code expandable="true" %}

```json
{
    "result": "rejected",
    "similarity": 0.59931052549619,
    "live": true,
    "document_type": "id",
    "generalDocuments": [
        {
            "pages": [
                {
                    "typeId": "utility-bill",
                    "final": {
                        "street": "Main Street",
                        "state": "California",
                        "city": "Los Angeles",
                        "country": "United States",
                        "postalCode": "90001",
                        "streetNumber": "123",
                        "county": "Los Angeles County",
                        "countryCode": "USA",
                        "documentIssued": "1/15/2025",
                        "documentIssuedTime": "2025-01-15T00:00:00",
                        "authority": "Bank of America, NA",
                        "address": "123 Main St, Los Angeles, CA 90001",
                        "formattedAddress": "123 Main St, Los Angeles, CA 90001, USA",
                        "latitude": 34.052235,
                        "longitude": -118.243683,
                        "fullName": "John Doe",
                        "firstName": "John",
                        "lastName": "Doe",
                        "permanent": null
                    },
                    "documentPages": [
                        {
                            "pageNumber": 1
                        }
                    ],
                    "pageNumber": 1,
                    "statuses": []
                }
            ],
            "documentType": "UTILITY_BILL",
            "permanent": null,
            "typeId": "utility_bill"
        }
    ],
    "reject_reason": {
        "value": "low_similarity",
        "description": "Low similarity"
    },
    "result_comment": "",
    "name": "John Doe",
    "errors": [
        "LOW_SIMILARITY"
    ],
    "face_images": 1,
    "id_card_front": {
        "Given_Names_en_US": "James",
        "Surname_en_US": "Smith",
        "Nationality_Code_en_US": "USA",
        "Sex_en_US": "M",
        "Date_of_Birth_en_US": "1/1/1980",
        "Date_of_Issue_en_US": "5/30/2015",
        "Document_Number_en_US": "A12345678",
        "Nationality_en_US": "USA",
        "Issuing_State_Code_en_US": "USA",
        "Date_of_Birth_ISO": "1980-01-01T00:00:00.000Z",
        "Date_of_Issued_ISO": "2015-05-30T00:00:00.000Z"
    },
    "id_card_back": {
        "Issuing_State_Code_en_US": "USA",
        "Authority_en_US": "Department of State",
        "Given_Names_en_US": "James",
        "Surname_en_US": "Smith",
        "Nationality_Code_en_US": "USA",
        "Sex_en_US": "M",
        "Date_of_Birth_en_US": "1/1/1980",
        "Date_of_Expiry_en_US": "5/30/2025",
        "Document_Number_en_US": "A12345678",
        "Nationality_en_US": "USA",
        "Date_of_Birth_ISO": "1980-01-01T00:00:00.000Z",
        "Date_of_Expiry_ISO": "2025-05-30T00:00:00.000Z",
        "mrz": "I<USA12345678<<<<<<<<<<<<<<<\n8001013M2505309USA<<<<<<<<<<<2\nSMITH<<JAMES<<<<<<<<<<<<<<<<<"
    },
    "suggested": {},
    "person": {
        "email": "johndoe@email.com",
        "phoneNumber": "+1234567890",
        "first_name": "James",
        "last_name": "Smith",
        "birthday": "1/1/1980",
        "birthday_time": "1980-01-01T00:00:00.000Z",
        "age": 45,
        "nationality": "USA",
        "document_number": "A12345678",
        "document_issued": "5/30/2015",
        "document_issued_time": "2015-05-30T00:00:00.000Z",
        "issuing_state": "USA",
        "sex": "M",
        "document_expires": "5/30/2025",
        "document_expires_time": "2025-05-30T00:00:00.000Z",
        "authority": "Department of State",
        "status": "FIELDS_MATCH",
        "mrz": "I<USA12345678<<<<<<<<<<<<<<<\n8001013M2505309USA<<<<<<<<<<<2\nSMITH<<JAMES<<<<<<<<<<<<<<<<<",
        "address": "123 Main St, Los Angeles, CA 90001, USA"
    },
    "questionnaires": [
        {
            "key": "agreement",
            "questions": [
                {
                    "key": "question1",
                    "answer": "John Doe"
                },
                {
                    "key": "question2",
                    "answer": "option4"
                },
                {
                    "key": "question3",
                    "answer": [
                        "option1",
                        "option2"
                    ]
                },
                {
                    "key": "question5",
                    "answer": 1
                },
                {
                    "key": "question6",
                    "answer": "readOnly answer"
                }
            ]
        }
    ],
    "geolocation": [
        {
            "key": "require_geolocation",
            "latitude": 34.05221168293059,
            "longitude": -118.24393094417908,
            "address": "123 Main St, Los Angeles, CA 90001, USA"
        }
    ],
    "technicalDetails": {
        "remoteAddress": "192.168.1.1",
        "userAgent": "PostmanRuntime/7.37.3",
        "countryCode": "US"
    },
    "videoCallStatus": [
        {
            "roomId": "RMf12391ce20597708d747587bdee8e715",
            "roomStatus": "ended",
            "compositionStatus": "available",
            "videoFileStatus": "available",
            "videoFileId": "av7YsrnDopwVmyzLtzkPKSiyWKVIaQDQZPtDfEq0"
        },
        {
            "roomId": "RM48170f8ee1235e27d5d09f8330b4f67f",
            "roomStatus": "empty",
            "compositionStatus": null,
            "videoFileStatus": null,
            "videoFileId": null
        }

}
```

{% endcode %}

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>result/ - Результат сесії <strong>KYB (бізнесу)</strong></summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/result</mark>](https://external-api.identomat.com/result)

\
**Опис:**

Використовуйте цей ендпоінт, щоб отримати результат сесії **KYB (верифікації бізнесу)**.

> Цей ендпоінт використовує новішу базову URL `external-api.identomat.com` та назви параметрів у форматі camelCase, на відміну від застарілого ендпоінту KYC.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

```bash
 curl https://external-api.identomat.com/result/ \
    -F 'companyKey={your-company-secret-key}' \
    -F 'sessionId={example-session-id-12345}'
```

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345"
}
```

***

**Структура відповіді**

Результати KYB повертаються в масиві `result.stepsResults`. Кожен запис відповідає кроку в потоці KYB.

<table><thead><tr><th width="174.73828125">Тип кроку</th><th>Опис</th></tr></thead><tbody><tr><td><code>company</code></td><td>Інформація про компанію, надана в потоці.</td></tr><tr><td><code>beneficiaries</code></td><td>Список UBO та представників (фізичних осіб чи компаній). Кожен окремий бенефіціар включає `sessionId` KYC, який можна отримати через ендпоінт KYC.</td></tr><tr><td><code>kyb-review</code></td><td>Фінальний статус перегляду та дані з довірених баз даних.</td></tr></tbody></table>

**Приклад результату:**

*за замовчуванням:*

{% code expandable="true" %}

```json
{
  "result": {
    "stepsResults": [
      {
        "key": "company",
        "type": "company",
        "result": {
          "companyName": "Acme Corp",
          "registrationNumber": "0000000000000",
          "registrationCountry": "United States",
          "taxId": "00000000",
          "dateOfIncorporation": "01/01/2010",
          "email": "contact@acme.com",
          "contactNumber": "+10000000000",
          "website": "www.acme.com",
          "companyEntityType": "Joint-stock company",
          "legalAddress": "123 Main Street",
          "countryCode": "US"
        },
        "status": "approved"
      },
      {
        "key": "beneficiaries-1",
        "type": "beneficiaries",
        "result": [
          {
            "entityType": "individual",
            "positions": ["shareholder", "representative"],
            "firstName": "John",
            "lastName": "Doe",
            "dateOfBirth": "01/01/1980",
            "ownershipPercentage": "25",
            "contactNumber": "+10000000000",
            "email": "john.doe@example.com",
            "sessionIds": ["example-kyc-session-id-0001"],
            "sessionUrl": "https://widget.identomat.com/?session_token=example-kyc-session-id-0001",
            "_id": "example-internal-id-0001"
          },
          {
            "entityType": "company",
            "positions": ["shareholder"],
            "companyName": "Partner Ltd",
            "registrationNumber": "000000000",
            "registrationCountry": "United Kingdom",
            "ownershipPercentage": "50",
            "contactNumber": "+44000000000",
            "email": "contact@partnerltd.com",
            "taxId": "000000000",
            "website": "www.partnerltd.com",
            "dateOfIncorporation": "01/01/2015",
            "sessionIds": ["example-kyc-session-id-0002"],
            "sessionUrl": "https://widget.identomat.com/?session_token=example-kyc-session-id-0002",
            "_id": "example-internal-id-0002"
          }
        ],
        "status": "approved"
      },
      {
        "key": "kyb-review",
        "type": "kyb-review",
        "status": "approved",
        "trustedDatabase": {
          "activityStatus": "ACTIVE",
          "companyName": "Acme Corp",
          "address": {
            "registeredOffice": {
              "streetName": "Main Street",
              "town": "New York",
              "zipCode": "10001"
            }
          },
          "lastUpdateTimestamp": 1777447248,
          "balanceSheets": {
            "last": {
              "year": 2023,
              "balanceSheetDate": "2023-12-31",
              "employees": 42,
              "netWorth": 500000.00,
              "totalAssets": 1200000.00
            },
            "all": [
              {
                "year": 2023,
                "balanceSheetDate": "2023-12-31",
                "employees": 42,
                "netWorth": 500000.00,
                "operatingRevenue": 800000.00,
                "equity": 360000.00,
                "totalAssets": 1200000.00
              },
              {
                "year": 2022,
                "balanceSheetDate": "2022-12-31",
                "employees": 38,
                "netWorth": 450000.00,
                "operatingRevenue": 750000.00,
                "equity": 320000.00,
                "totalAssets": 900000.00
              }
            ]
          }
        }
      }
    ],
    "technicalDetails": {
      "remoteAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0",
      "countryCode": "US"
    }
  }
}
```

{% endcode %}

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>delete/ - Видалення даних сесії</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/delete/</mark>](https://widget.identomat.com/external-api/delete/)

**Опис:**

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

\
**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

```bash
curl https://widget.identomat.com/external-api/delete/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'session_token={some_session_token}'
```

**Приклади параметрів запиту:**

```json
{
  "company_key": "your-company-secret-key",
  "session_token": "defg"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
true
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>export-session-as-pdf - Експорт сесії</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/export-session-as-pdf</mark>](https://external-api.identomat.com/export-session-as-pdf)

**Опис:**

Цей ендпоінт дозволяє експортувати дані, пов'язані з конкретною сесією, у вигляді завантажуваного PDF-документа. Ви можете вибрати включення повних деталей сесії, результатів скринінгу та/або документів підтвердження адреси. Принаймні одна опція експорту має бути встановлена як `true`.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

* `exportSession` *(boolean, необов'язковий)* – Вказує, чи потрібно експортувати повні дані сесії.
* `exportScreening` *(boolean, необов'язковий)* – Визначає, чи включати результати скринінгу в експорт.
* `exportProofOfAddress` *(boolean, необов'язковий)* - Визначає, чи включати документи підтвердження адреси в експорт.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/export-session-as-pdf \    
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "sessionId": "example-session-id-12345"
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345",
  "exportSession": true,
  "exportScreening": false,
  "exportProofOfAddress": false
}
```

**Приклади результату:**

*за замовчуванням:*

```json
PDF document of session
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

### Доступ до даних та інше

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

<details>

<summary>result/card-front/ - Зображення лицьової сторони картки</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/result/card-front/</mark>](https://widget.identomat.com/external-api/result/card-front/)

**Опис:**

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

\
**Параметри:**

* `company_key` *(string, обов'язковий)* - Секретний ключ компанії.
* `session_token` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

```bash
curl https://widget.identomat.com/external-api/result/card-front/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'session_token={example-session-id-12345}'
```

**Приклади результату:**

*за замовчуванням:*

```
Card front side image
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>result/card-back/ - Зображення зворотної сторони картки</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/result/card-back/</mark>](https://widget.identomat.com/external-api/result/card-back/)

**Опис:**

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

\
**Параметри:**

* `company_key` *(string, обов'язковий)* - Секретний ключ компанії.
* `session_token` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

```bash
curl https://widget.identomat.com/external-api/result/card-back/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'session_token={example-session-id-12345}'
```

**Приклади результату:**

*за замовчуванням:*

```
Card back side image
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>result/passport/ - Зображення сторінки з фото паспорта</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/result/passport/</mark>](https://widget.identomat.com/external-api/result/passport/)

**Опис:**

Цей ендпоінт повертає зображення паспорта, поданого під час сесії.

\
**Параметри:**

* `company_key` *(string, обов'язковий)* - Секретний ключ компанії.
* `session_token` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

```bash
curl https://widget.identomat.com/external-api/result/passport/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'session_token={example-session-id-12345}'
```

**Приклади результату:**

*за замовчуванням:*

```
Passport image
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>result/face/ - Зображення обличчя</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/result/face/</mark>](https://widget.identomat.com/external-api/result/face/)

**Опис:**

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

\
**Параметри:**

* `company_key` *(string, обов'язковий)* - Секретний ключ компанії.
* `session_token` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

```bash
curl https://widget.identomat.com/external-api/result/face/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'session_token={example-session-id-12345}'
```

**Приклади результату**:

*за замовчуванням:*

```
Face image
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>result/face-video/ - Відео руху обличчя</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/result/face-video/</mark>](https://widget.identomat.com/external-api/result/face-video/)

**Опис:**

Цей ендпоінт повертає відео, використане під час перевірки живості в процесі верифікації особи.

\
**Параметри:**

* `company_key` *(string, обов'язковий)* - Секретний ключ компанії.
* `session_token` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

```bash
curl https://widget.identomat.com/external-api/result/face-video/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'session_token={example-session-id-12345}'
```

**Приклади результату:**

*за замовчуванням:*

```
Face video
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>result/face-document/ - Селфі з ID</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/result/face-document/</mark>](https://widget.identomat.com/external-api/result/face-document/)

**Опис:**

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

\
**Параметри:**

* `company_key` *(string, обов'язковий)* - Секретний ключ компанії.
* `session_token` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

```bash
curl https://widget.identomat.com/external-api/result/face-document/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'session_token={example-session-id-12345}'
```

**Приклади результату:**

*за замовчуванням:*

```
Selfie with ID (image)
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>result/general-document/ - Зображення чи PDF підтвердження адреси</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/result/general-document/</mark>](https://widget.identomat.com/external-api/result/general-document/)

**Опис:**

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

\
**Параметри:**

* `company_key` *(string, обов'язковий)* - Секретний ключ компанії.
* `session_token` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.
* `typeId` *(string, обов'язковий)* – Ідентифікатор типу документа. Допустимі значення включають:
  * `bank-statement`
  * `utility-bill`
  * `vehicle-registration-certificate-front`
  * `vehicle-registration-certificate-back`
  * `drivers-license`

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

```bash
curl https://widget.identomat.com/external-api/result/general-document/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'session_token={example-session-id-12345}' \
    -F 'typeId={example-type-id}'
```

**Приклади параметрів запиту:**

```json
{
  "company_key": "your-company-secret-key",
  "session_token": "defg",
  "typeId": "bank-statement"
}
```

**Приклади результату:**

*за замовчуванням:*

```
Image or PDF of document
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>get-session-main-document-face-photo - Отримати фото обличчя з основного документа</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/get-session-main-document-face-photo</mark>](https://external-api.identomat.com/get-session-main-document-face-photo)

**Опис:**

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

\
**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/get-session-main-document-face-photo \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "sessionId": "example-session-id-12345"
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": "data:text/plain;base64String"
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

*notFound:*

```json
{  
    "argumentError": "face-photo-not-found"
}
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>list-session-activities - Список активностей сесії</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/list-session-activities</mark>](https://external-api.identomat.com/list-session-activities)

**Опис:**

Цей ендпоінт отримує список активностей, пов'язаних із конкретною сесією.

\
**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/list-session-activities \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "sessionId": "example-session-id-12345"
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": [
    {
      "id": "6162636465666768696a6b6c",
      "type": "PAGE_LOADED",
      "time": "2021-12-29T11:30:39.086Z",
      "data": {}
    },
    {
      "id": "5ff45878f44e95bbf987a801",
      "type": "PAGE_LOADED",
      "time": "2011-12-29T11:30:39.086Z",
      "data": {}
    }
  ]
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>get-session-statistical-summary - Статистичне зведення сесії</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/get-session-statistical-summary</mark>](https://external-api.identomat.com/get-session-statistical-summary)

**Опис:**

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

\
**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

```bash
curl -X POST https://external-api.identomat.com/get-session-statistical-summary \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "sessionId": "example-session-id-12345"}'
```

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": [
    {
      "sessionStartDate": "2021-12-29T11:30:40.000Z",
      "sessionTimeSpan": 8000,
      "scanDocumentStartTime": "2021-12-29T11:30:41.000Z",
      "scanDocumentEndTime": "2021-12-29T11:30:43.000Z",
      "scanDocumentAttempts": 1,
      "scanDocumentFailReason": null,
      "livenessStartTime": "2021-12-29T11:30:45.000Z",
      "livenessEndTime": "2021-12-29T11:30:48.000Z",
      "livenessFailReasons": null,
      "sessionTerminationStep": null,
      "sessionTerminationReasons": null
    }
  ]
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>get-visual-markers - Отримати візуальні маркери документа</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/get-visual-markers</mark>](https://external-api.identomat.com/get-visual-markers)

**Опис:**

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

\
**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

```bash
curl -X POST 'https://external-api.identomat.com/get-visual-markers' \
    -H 'Content-Type: application/json' \
    -d '{
    "companyKey": "your-company-secret-key",
    "sessionId": "example-session-id-12345"
}'
```

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": "data:application/x-tar;base64,base64String"
}
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

### AML-скринінг

Використовуйте ці ендпоінти для пошуку в глобальних базах даних скринінгу щодо санкцій, PEP, регуляторних дій та інших індикаторів ризику. Ви можете виконувати одноразові пошуки, отримувати детальні профілі та налаштовувати постійний моніторинг осіб, щоб отримувати сповіщення про зміну їхнього статусу скринінгу.

<details>

<summary>search-screening-person - Пошук особи в базах даних скринінгу</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/search-screening-person</mark>](https://external-api.identomat.com/search-screening-person)

**Опис:**

Використовуйте цей ендпоінт для пошуку осіб у глобальних базах даних скринінгу, включно з санкціями, PEP (публічно значущими особами), регуляторними діями та іншим.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `query` *(object, обов'язковий)* – Параметри для запиту до бази даних.
  * `fullName` *(string, обов'язковий)* – Повне ім'я особи.
  * `birthdayTimeFrom` *(string, необов'язковий)* – Початкова дата та час діапазону дня народження у форматі ISO 8601.
  * `scoreThreshold` *(integer, обов'язковий)* – Мінімальний бал, необхідний для результатів запиту.
* `offset` *(integer, необов'язковий)* – Кількість елементів, які потрібно пропустити з початку результатів.
* `limit` *(integer, необов'язковий)* – Максимальна кількість елементів для повернення в результатах запиту.

**Глосарій об'єктів:**

* **`Sanctioned entity` (Санкціонований об'єкт)**: Компанії, фізичні особи чи інші об'єкти, які уряд визначив для заборони конкретних взаємодій із ними.
* **`Sanction-linked entity` (Об'єкт, пов'язаний із санкціями)**: Об'єкти, включно з компаніями та фізичними особами, які мають пряме відношення до санкціонованого об'єкта. Це також включає компанії, які є непрямими дочірніми підприємствами санкціонованих об'єктів, незалежно від відсотка володіння санкціонованого об'єкта.
* **`Counter-sanctioned entity` (Контрсанкціонований об'єкт)**: Об'єкти, внесені до санкційних списків недемократичних країн, часто спрямовані проти продемократичних активістів, журналістів та правозахисників.
* **`Debarred entity` (Виключений об'єкт)**: Компанії чи фізичні особи, виключені з державних закупівель, зазвичай через шахрайство при виконанні державного контракту.
* **`Politician (Politically Exposed Persons)` (Політик — публічно значуща особа)**: Особи, які нині чи раніше обіймали посаду з політичним впливом.
* **`Close associate` (Близький партнер)**: Члени сім'ї та ключові ділові партнери публічно значущих осіб (PEP). Ці особи часто використовуються як номінальні особи чи прикриття для приховування незаконних фінансових доходів.
* **`Person of Interest` (Особа інтересу)**: Особи, під підвищеною увагою через суспільний інтерес, які не відповідають загальним визначенням публічно значущих осіб і не є санкціонованими.
* **`Regulator action` (Регуляторна дія)**: Компанії, до яких застосовано примусові заходи з боку галузевого регуляторного органу.
* **`Regulator warning` (Регуляторне попередження)**: Компанії, внесені до списку попереджень чи сповіщень галузевим регуляторним органом.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/search-screening-person \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey":"your-company-secret-key",
        "query":
            {
            "birthdayTimeFrom":"1980-11-07T13:07:59.790Z",
            "fullName":"John Doe",
            "scoreThreshold":80
            },
        "offset":0,
        "limit":100
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "query": {
    "birthdayTimeFrom": "1980-11-07T13:07:59.790Z",
    "fullName": "John Doe",
    "scoreThreshold": 80
  },
  "offset": 0,
  "limit": 100
}
```

**Приклади результату:**

*за замовчуванням - немає результатів для особи:*

```json
{
    "result": []
}
```

*за замовчуванням - особу знайдено:*

```json
{
    "result": [
        {
            "score": 100,
            "name": "John Doe",
            "personId": "67137933a2176f0797f1e657",
            "entityType": "person",
            "topics": [
                "Sanctioned entity",
                "Wanted person",
                "Person of interest",
                "Politician"
            ]
        }
    ]
}
```

*companyMissing:*

```json
{
  "argumentError": "company-missing"
}
```

*accessDenied:*

```json
{
  "argumentError": "access-denied"
}
```

</details>

<details>

<summary>get-screening-person-details - Отримати деталі особи з баз даних скринінгу</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/get-screening-person-details</mark>](https://external-api.identomat.com/get-screening-person-details)<br>

**Опис:**

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

\
**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `personId` *(string, обов'язковий)* – Унікальний ідентифікатор особи.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/get-screening-person-details \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey":"your-company-secret-key",
        "personId":"example-person-id-12345"
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "personId": "example-person-id-12345"
}
```

**Приклади результату:**

*за замовчуванням:*

{% code expandable="true" %}

```json
{
    "result": {
        "entityType": "person",
        "firstName": "John",
        "middleName": "Doe",
        "lastName": "Smith",
        "gender": "male",
        "birthdayTime": "1952-10-07",
        "nationality": "US",
        "extraDetails": [
            {
                "groupName": "Profile",
                "details": [
                    {
                        "detailName": "John Doe Smith",
                        "properties": [
                            {
                                "propertyName": "Position",
                                "value": [
                                    "President of US (2012-)",
                                    "chairperson",
                                    "party leader"
                                ],
                                "type": "list"
                            },
                            {
                                "propertyName": "Name",
                                "value": [
                                    "John Doe Smith",
                                    "约翰·多·史密斯",
                                    "Джон Доу Сміт",
                                    {
                                        "propertyName": "Alias",
                                        "value": [
                                            "John Smith"
                                        ],
                                        "type": "list"
                                    },
                                    {
                                        "groupName": "Position occupied",
                                        "details": [
                                            {
                                                "detailName": "President",
                                                "properties": [
                                                    {
                                                        "propertyName": "Name",
                                                        "value": [
                                                            "President of US",
                                                            "President"
                                                        ],
                                                        "type": "string"
                                                    },
                                                    {
                                                        "propertyName": "Start Date",
                                                        "value": [
                                                            "1999-08-16"
                                                        ],
                                                        "type": "date"
                                                    },
                                                    {
                                                        "propertyName": "End Date",
                                                        "value": [
                                                            "2000-05-07"
                                                        ],
                                                        "type": "date"
                                                    },
                                                    {
                                                        "propertyName": "Status",
                                                        "value": [
                                                            "active"
                                                        ],
                                                        "type": "string"
                                                    }
                                                ]
                                            },
                                            {
                                                "groupName": "Sanctions",
                                                "details": [
                                                    {
                                                        "detailName": "Department of Foreign Affairs and Trade",
                                                        "properties": [
                                                            {
                                                                "propertyName": "Start Date",
                                                                "value": [
                                                                    "2022-02-28"
                                                                ],
                                                                "type": "date"
                                                            },
                                                            {
                                                                "propertyName": "Authority",
                                                                "value": [
                                                                    "Department of Foreign Affairs and Trade"
                                                                ],
                                                                "type": "string"
                                                            },
                                                            {
                                                                "propertyName": "Program",
                                                                "value": [
                                                                    ""
                                                                ],
                                                                "type": "string"
                                                            },
                                                            {
                                                                "propertyName": "Entity",
                                                                "value": [
                                                                    "Q772247"
                                                                ],
                                                                "type": "string"
                                                            },
                                                            {
                                                                "propertyName": "Summary",
                                                                "value": [
                                                                    "Instrument of first designation and declaration: Autonomous Sanctions ....."
                                                                ],
                                                                "type": "string"
                                                            },
                                                            {
                                                                "propertyName": "Source Url",
                                                                "value": [
                                                                    "https://www.dfat.gov.au/international-relations/security/sanctions/Pages3/"
                                                                ],
                                                                "type": "url"
                                                            }
                                                        ]
                                                    }
                                                ]
                                            }
                                        ]
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
```

{% endcode %}

*companyMissing:*

```json
{
  "argumentError": "company-missing"
}
```

*accessDenied:*

```json
{
  "argumentError": "access-denied"
}
```

</details>

<details>

<summary>monitor-screening-query - Встановити особу на моніторинг</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/monitor-screening-query</mark>](https://external-api.identomat.com/monitor-screening-query)

**Опис:**

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

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `query` *(object, обов'язковий)* – Параметри для запиту до бази даних.
  * `fullName` *(string, обов'язковий)* – Прізвище особи.
  * `birthdayTimeFrom` *(string, необов'язковий)* – Початкова дата та час діапазону дня народження у форматі ISO 8601.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/monitor-screening-query \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey":"your-company-secret-key", 
        "query": 
            {
            "fullName": "John Doe",  
            "birthdayTimeFrom": "1982-11982-12-12T00:00:00Z"
            }
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "query": {
    "fullName": "John Doe",
    "birthdayTimeFrom": "1982-12-12T00:00:00Z"
  }
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": "64ad3b14090678e34512eab8"
}
```

*Уже на моніторингу:*

```json
{
    "argumentError": "already-exists"
}
```

</details>

<details>

<summary>remove-screening-query-from-monitoring - Видалити особу з моніторингу</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/remove-screening-query-from-monitoring</mark>](https://external-api.identomat.com/remove-screening-query-from-monitoring)

**Опис:**

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

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `id` *(string, обов'язковий)* - ID запиту моніторингу.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/remove-screening-query-from-monitoring \
  -H 'Content-Type: application/json' \
  -d '{ 
      "companyKey": "your-company-secret-key", 
      "id": "64ad3b14090678e34512eab8"
      }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "id": "64ad3b14090678e34512eab8"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{ 
    "result": true
}
```

</details>

<details>

<summary>list-screening-monitoring-records - Список записів скринінгу, що моніторяться</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/list-screening-monitoring-records</mark>](https://external-api.identomat.com/list-screening-monitoring-records)

**Опис:**

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

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `start` *(integer, необов'язковий)* – Кількість елементів, які потрібно пропустити з початку результатів.
* `limit` *(integer, необов'язковий)* – Максимальна кількість записів для повернення.
* `date` *(string, необов'язковий, формат ISO 8601)* – Фільтрує записи після конкретної дати. Якщо дату не вказано, буде повернено весь список.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/list-screening-monitoring-records \
  -H 'Content-Type: application/json' \
  -d '{
      "companyKey":"your-company-secret-key", 
      "start":0, 
      "limit": 50
      }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "start": 0,
  "limit": 50,
  "date":"2023-07-10T12:26:00.576Z
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": {
    "start": 0,
    "limit": 50,
    "total": 4,
    "data": [
      {"fullName":"John Smith1","id":"64ad3b14090678e34512eab8"},
      {"fullName":"John Smith2","id":"64ad3ef45fcf054afc73ebb4", "lastUpdatedDate": "2023-07-01T10:50:42.389Z"},
      {"fullName":"John Smith3","id":"64ad3f3a8b3f54aca29fc0a2", "lastUpdatedDate": "2023-07-20T10:50:42.389Z"},
      {"fullName":"John Smith4","id":"64ad3f3a8b3f54aca29fc0a3"}
    ]
  }
}
```

</details>

### **Керування чорним списком**

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

<details>

<summary>add-blacklist-record - Додати особу до чорного списку</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/add-blacklist-record</mark>](https://external-api.identomat.com/add-blacklist-record)

**Опис:**

Додає особу до чорного списку на основі ідентифікаційних атрибутів, таких як ім'я, номер документа чи особистий номер.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `query` *(object of strings, обов'язковий)* - Об'єкт, що містить деталі запиту. **Має включати** `reason` та **принаймні одне з** наступного: `firstName`, `lastName`, `personalNumber`, `documentNumber`, `birthday`.
  * firstName (string, необов'язковий) - Ім'я особи.
  * lastName (string, необов'язковий) - Прізвище особи.
  * personalNumber (string, необов'язковий) - Особистий ідентифікаційний номер.
  * documentNumber (string, необов'язковий) - Номер документа (наприклад, з ID чи паспорта).
  * birthday (string, необов'язковий) - Дата народження у форматі ISO 8601 (наприклад, 1990-05-14).
  * reason (string, обов'язковий) - Причина внесення особи до чорного списку.

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

{% code overflow="wrap" %}

```bash
curl -X POST 'https://external-api.identomat.com/add-blacklist-record' \
    -H 'Content-Type: application/json' \
    -d'{
        "companyKey": "your-company-secret-key",
        "query": {
            "firstName": "John",
            "lastName": "Doe",
            "personalNumber": "12345678901",
            "documentNumber": "123ABC123",
            "birthday": "1980-01-01T00:00:00.000Z",
            "reason": "Reason for adding to blacklist",
            "notes" : "Fraud-related activity"
                }
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
    "companyKey": "your-company-secret-key",
    "query": {
        "firstName": "John",
        "lastName": "Doe",
        "personalNumber": "12345678901",
        "documentNumber": "123ABC123",
        "birthday": "1980-01-01T00:00:00.000Z",
        "reason": "Reason for adding to blacklist",
        "notes" : "Fraud-related activity"
    }
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
    "result": "64ad3b14090678e34512eab8"
}
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

*invalidCompanyKey:*

```json
{
  "argumentError": "invalid-company-key"
}
```

*alreadyExists*

```json
{  
  "argumentError": "already-exists"
}
```

</details>

<details>

<summary>remove-blacklist-record - Видалити запис із чорного списку</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/remove-blacklist-record</mark>](https://external-api.identomat.com/remove-blacklist-record)

**Опис:**

Видаляє раніше доданий запис із чорного списку.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `id` (string, обов'язковий) - ID запису чорного списку.

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

{% code overflow="wrap" %}

```bash
curl -X POST 'https://external-api.identomat.com/remove-blacklist-record' \
    -H 'Content-Type: application/json' \
    -d'{
        "companyKey": "your-company-secret-key",
        "id": "682b09e4400b3a00067ebcf7"
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
    "companyKey": "your-company-secret-key",
    "id": "682b09e4400b3a00067ebcf7"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
    "result": true
}
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

*invalidCompanyKey:*

```json
{
"argumentError": "invalid-company-key"
}
```

*idNotFound:*

```json
{  
  "argumentError": "not-found"
}
```

</details>

<details>

<summary>list-blacklist-records - Список усіх записів чорного списку компанії</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/list-blacklist-records</mark>](https://external-api.identomat.com/list-blacklist-records)

**Опис:**

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

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* query (object of strings, необов'язковий) - Необов'язкові поля фільтра:
  * `offset` (number, необов'язковий) - Кількість записів, які потрібно пропустити з початку.
  * `limit` (number, необов'язковий) - Максимальна кількість записів для повернення.

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

{% code overflow="wrap" %}

```bash
curl -X POST 'https://external-api.identomat.com/list-blacklist-records' \
    -H 'Content-Type: application/json' \
    -d'{
        "companyKey": "your-company-secret-key"
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
    "companyKey": "your-company-secret-key"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
    "result": {
        "offset": 0,
        "limit": 100,
        "total": 1,
        "data": [
            {
                "firstName": "John",
                "lastName": "Doe",
                "documentNumber": "123ABC123",
                "personalNumber": "012345678901",
                "birthday": "1980-01-01T00:00:00.000Z",
                "notes": "Fraud-related activity",
                "reason": "Reason for adding to blacklist",
                "id": "64f4d0ec35f5bb20a8022012"
            }
        ]
    }
}
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

*invalidCompanyKey:*

```json
{
"argumentError": "invalid-company-key"
}
```

*noRecord:*

```json
{
    "result": {
        "offset": 0,
        "limit": 100,
        "total": 0,
        "data": []
    }
}
```

</details>

### **Відеодзвінок**

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

<details>

<summary>get-video-call-shots - Знімки відеодзвінка</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/get-video-call-shots</mark>](https://external-api.identomat.com/get-video-call-shots)

**Опис:**

Отримує всі знімки екрана (shots), зроблені оператором під час сесії відеодзвінка. Ці зображення слугують частиною доказів, зібраних під час верифікації KYC.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/get-video-call-shots \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "sessionId": "example-session-id-12345"
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": "data:application/x-tar;base64,base64String"
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>get-video-call-videos - Відео відеодзвінка</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/get-video-call-videos</mark>](https://external-api.identomat.com/get-video-call-videos)

**Опис:**

Отримує відеозаписи з сесії відеодзвінка.\
Ендпоінт підтримує два режими отримання:

1. **Пріоритетний (рекомендовано):** отримати **один відеофайл** за допомогою параметра `fileId`.
2. **Застарілий:** отримати **всі відеофайли одразу** (повертається у вигляді архіву `.tar`).

Використання `fileId` рекомендовано для кращої продуктивності, зменшеного розміру payload та підвищеної надійності.

**Параметри:**

**Обов'язкові**

* **companyKey** *(string)* — Секретний ключ компанії.
* **sessionId** *(string)* — Унікальний ідентифікатор сесії.

**Необов'язкові (рекомендовані)**

* **fileId** *(string)* — Унікальний ID відеофайлу, який ви хочете отримати.\
  Якщо надано, ендпоінт повертає **лише вказаний відеофайл** замість повного архіву.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/get-video-call-videos \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "sessionId": "example-session-id-12345",
        "fileId": "abc123xyz"
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345",
  "fileId": "abc123xyz"
}
```

**Приклади результату:**

один файл:

```json
"result": {
    "contentType": "video/mp4"
  }
```

*всі файли:*

```json
"result": {
    "contentType": "application/x-tar"
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

*notFound:*

```json
{  
    "argumentError": "not-found"
}
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>end-video-call - Завершити відеодзвінок для підключеного користувача</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/end-video-call</mark>](https://external-api.identomat.com/end-video-call)

**Опис:**

Вручну завершує активну сесію відеодзвінка для підключеного користувача. Цей ендпоінт зазвичай використовується системою для примусового закриття сесії, яка все ще триває.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/get-video-call-videos \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "sessionId":"example-session-id-12345"
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345"
}
```

**Приклади результату:**

*за замовчуванням:*

```
{ }
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

</details>

### Вкладення опитувальника

Використовуйте ці ендпоінти для керування файлами, пов'язаними із запитаннями типу «вкладення» у кроках опитувальника. Файли можуть надходити з декількох джерел — завантажені користувачем під час сесії KYC, подані оператором у Manage, визначені статично в конфігурації, або завантажені програмно через API.

<details>

<summary>get-question-file - Отримати файл із запитання</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/get-question-file</mark>](https://external-api.identomat.com/get-question-file)

**Опис:**

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

\
**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* - Унікальний ідентифікатор сесії.
* `stepKey` *(string, обов'язковий)* – Унікальний ключ кроку опитувальника.
* `questionKey`*(string, обов'язковий)* – Унікальний ключ запитання в межах опитувальника.
* `fileIndex` *(integer, необов'язковий)* – Індекс файлу, коли до запитання завантажено декілька файлів. Використовується для посилання на конкретний файл у межах вкладень запитання.

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

```bash
curl -X POST 'https://external-api.identomat.com/get-question-file' \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "sessionId": "example-session-id-12345",
        "stepKey": "user-questionnaire-1a2b3c",
        "questionKey": "question-1",
        "fileIndex": 0
}'
```

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345",
  "stepKey": "user-questionnaire-1",
  "questionKey": "question-1",
  "fileIndex": 0
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": {
        "contentType": "application/pdf | image/png | image/jpeg"
    }
}
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

</details>

<details>

<summary>upload-file - Завантажити файл до запитання</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/upload-file</mark>](https://external-api.identomat.com/upload-file)

**Опис:**

Завантажує файл до конкретного запитання типу «вкладення» в межах кроку опитувальника. Файл має бути наданий у вигляді data URI, закодованого у base64. Повертає `fileId`, який можна використати для отримання чи видалення файлу пізніше.

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

* `data:application/pdf;base64,...`
* `data:image/jpeg;base64,...`
* `data:image/png;base64,...`

**Параметри:**

* `companyKey` *(string, обов'язковий)* — Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* — Унікальний ідентифікатор сесії.
* `stepKey` *(string, обов'язковий)* — Унікальний ключ кроку опитувальника.
* `questionKey` *(string, обов'язковий)* — Унікальний ключ запитання типу «вкладення».
* `content` *(string, обов'язковий)* — Вміст файлу у вигляді data URI, закодованого у base64 (наприклад, `data:image/png;base64,...`).

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

```bash
curl -X POST https://external-api.identomat.com/upload-file \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "sessionId": "example-session-id-12345",
        "stepKey": "user-questionnaire-1a2b3c",
        "questionKey": "question-1",
        "content": "data:image/png;base64,iVBORw0KGgo..."
    }'
```

**Приклад параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345",
  "stepKey": "user-questionnaire-1a2b3c",
  "questionKey": "question-1",
  "content": "data:image/png;base64,iVBORw0KGgo..."
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": "9iomy86NuoOQnK7l2puTgiSapWf22xFwn6KRn4FG"
}
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

</details>

<details>

<summary>get-file - Отримати файл із запитання</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/get-file</mark>](https://external-api.identomat.com/get-file)

**Опис:**

Отримує файл, який був програмно завантажений через ендпоінт `upload-file`.

**Параметри:**

* `companyKey` *(string, обов'язковий)* — Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* — Унікальний ідентифікатор сесії.
* `stepKey` *(string, обов'язковий)* — Унікальний ключ кроку опитувальника.
* `questionKey` *(string, обов'язковий)* — Унікальний ключ запитання типу «вкладення».
* `filename` *(string, обов'язковий)* — ID файлу, повернутий `upload-file`.

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

```bash
curl -X POST https://external-api.identomat.com/get-file \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "sessionId": "example-session-id-12345",
        "stepKey": "user-questionnaire-1a2b3c",
        "questionKey": "question-1",
        "filename": "9iomy86NuoOQnK7l2puTgiSapWf22xFwn6KRn4FG"
    }'
```

**Приклад параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345",
  "stepKey": "user-questionnaire-1a2b3c",
  "questionKey": "question-1",
  "filename": "9iomy86NuoOQnK7l2puTgiSapWf22xFwn6KRn4FG"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
File stream
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

</details>

<details>

<summary>delete-file - Видалити файл із запитання</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/delete-file</mark>](https://external-api.identomat.com/delete-file)

**Опис:**

Остаточно видаляє раніше завантажений файл із запитання типу «вкладення». Ця операція незворотна.

**Параметри:**

* `companyKey` *(string, обов'язковий)* — Секретний ключ компанії.
* `sessionId` *(string, обов'язковий)* — Унікальний ідентифікатор сесії.
* `stepKey` *(string, обов'язковий)* — Унікальний ключ кроку опитувальника.
* `questionKey` *(string, обов'язковий)* — Унікальний ключ запитання типу «вкладення».
* `filename` *(string, обов'язковий)* — ID файлу, повернутий `upload-file`.

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

```bash
curl -X POST https://external-api.identomat.com/delete-file \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "sessionId": "example-session-id-12345",
        "stepKey": "user-questionnaire-1a2b3c",
        "questionKey": "question-1",
        "filename": "9iomy86NuoOQnK7l2puTgiSapWf22xFwn6KRn4FG"
    }'
```

**Приклад параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionId": "example-session-id-12345",
  "stepKey": "user-questionnaire-1a2b3c",
  "questionKey": "question-1",
  "filename": "9iomy86NuoOQnK7l2puTgiSapWf22xFwn6KRn4FG"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": true
}
```

*sessionNotFound:*

```json
{
  "argumentError": "session-not-found"
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

</details>

### Інші методи

Використовуйте ці ендпоінти для керування групами, користувачами та конфігураціями сесій у Manage. Групи можна використовувати для контролю того, які оператори мають доступ до конкретних сесій. Ендпоінти керування користувачами дозволяють програмно створювати, переглядати список та видаляти користувачів платформи. Ви також можете отримати повні деталі конфігурації сесії за її ID.

<details>

<summary>list-groups - Список груп</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/list-groups</mark>](https://external-api.identomat.com/list-groups)

**Опис:**

Отримує список груп, пов'язаних із зазначеною компанією. Кожна група включає свій ID, назву, опис та список учасників.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/list-groups \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key"
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": [
        {
            "id": "650976e8dc32104b8bb1757e",
            "name": "Group name",
            "description": "Group description",
            "memberUserIds": [
                        "64f4d0ec35f5bb20a8022012",
                        "64f4d10435f5bb20a8022013",
                        "64f4d12335f5bb20a8022014"
              ]
        }
    ]
}
```

*noGroups:*

```json
{
  "result": []
}
```

*notFound:*

```json
{  
    "argumentError": "not-found"
}
```

</details>

<details>

<summary>make-group - Створити нову групу</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/make-group</mark>](https://external-api.identomat.com/make-group)

**Опис:**

Створює нову групу користувачів у межах зазначеної компанії. Групу можна використати для керування правами доступу, призначення сесій чи організації користувачів.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `name` *(string, обов'язковий)* – Назва нової групи.
* `description` (string, необов'язковий) - Опис нової групи.
* `memberIds` *(array of strings, необов'язковий)* – Список ID користувачів для додавання до групи.

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

{% code overflow="wrap" %}

```bash
curl -X POST 'https://external-api.identomat.com/make-group' \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "name": "Group name",
        "description": "Group description",
        "memberIds": 
            [ 
            "user1-id", 
            "user2-id"
            ]
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
    "companyKey": "your-company-secret-key",
    "name": "Group name",
    "description": "Group description",
    "memberIds": [ "user1-id", "user2-id"
    ]
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
    "result": {
        "id": "6784c6d768cb9e8a891087e1"
    }
}
```

*wrongParameter:*

```json
{
    "argumentError":"wrong-parameters",
    "errorSourceGroup":"service-module-server-external"
}
```

</details>

<details>

<summary>change-group - Оновити наявну групу</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/make-group</mark>](https://external-api.identomat.com/make-group)

**Опис:**

Дозволяє змінити наявну групу, оновивши її назву чи змінивши учасників групи. **Щоб зберегти наявних учасників у групі, ви маєте включити їхні ID до списку.**

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `groupId` *(string, обов'язковий)* – Унікальний ідентифікатор групи.
* `name` *(string, необов'язковий)* – Назва нової групи.
* `description` *(string, необов'язковий)* - Опис нової групи.
* `memberIds` *(array of strings, необов'язковий)* – Список ID користувачів для додавання чи видалення з групи. Щоб зберегти наявних учасників у групі, ви маєте включити їхні ID до списку.

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

{% code overflow="wrap" %}

```bash
curl -X POST 'https://external-api.identomat.com/change-group' \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "groupId": "64a50a0c6c2ff7f9a1f12833",
        "name": "Group 1",
        "description": "Group 1 description",
        "memberIds": 
            [ 
            "user1-id", 
            "user2-id"
            ]
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
    "companyKey": "your-company-secret-key",
    "groupId": "64a50a0c6c2ff7f9a1f12833",
    "name": "Group 1",
    "description": "Group 1 description",
    "memberIds": [ "user1-id", "user2-id"
    ]
}
```

**Приклади результату:**

*за замовчуванням:*

```
{}
```

*wrongParameter:*

```json
{
    "argumentError":"wrong-parameters",
    "errorSourceGroup":"service-module-server-external"
}
```

</details>

<details>

<summary>delete-group - Видалити групу</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/delete-group</mark>](https://external-api.identomat.com/delete-group)

**Опис:**

Дозволяє остаточно видалити групу із системи.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `groupId` *(string, обов'язковий)* – Унікальний ідентифікатор групи.

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

{% code overflow="wrap" %}

```bash
curl -X POST 'https://external-api.identomat.com/delete-group' \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key",
        "groupId": "64b63613ad6f7ccaec256773"
    ]
}'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
    "companyKey": "your-company-secret-key",
    "groupId": "64b63613ad6f7ccaec256773"
    ]
}
```

**Приклади результату:**

*за замовчуванням:*

```
{}
```

*wrongParameter:*

```json
{
    "argumentError":"wrong-parameters",
    "errorSourceGroup":"service-module-server-external"
}
```

</details>

<details>

<summary>list-users - Список користувачів</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/list-users</mark>](https://external-api.identomat.com/list-users)

**Опис:**

Цей ендпоінт отримує список користувачів, пов'язаних із компанією.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/list-users \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey": "your-company-secret-key"
        }'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
    "result": [
        {
            "id": "user_id",
            "username": "user@identomat.com",
            "roles": [
                "administrator",
                "operator",
                "call_center_operator"
            ]
        }
    ]
}
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

*invalidAccess:*

```json
{
  "argumentError": "invalid-access"
}
```

</details>

<details>

<summary>create-user - Створити користувача</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/create-user</mark>](https://external-api.identomat.com/create-user)

**Опис:**

Створює нового користувача для платформи Identomat (Manage).

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `email` *(string, обов'язковий)* - Адреса електронної пошти нового користувача.
* `emailVerified` (boolean, необов'язковий) - Чи слід позначати email як підтверджений. За замовчуванням `false`.
* `password` (string, обов'язковий) - Пароль користувача (мінімум 8 символів).
* `firstName` (string, необов'язковий) - Ім'я користувача.
* `lastName` (string, необов'язковий) - Прізвище користувача.
* `rights` (array of strings, необов'язковий) - Список ролей для призначення користувачеві. Якщо не вказано, за замовчуванням `call_center_operator`. Допустимі значення:
  * `call_center_operator`
  * `operator`
  * `administrator`

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

{% code overflow="wrap" %}

```bash
curl -X POST 'https://external-api.identomat.com/create-user' \
    -H 'Content-Type: application/json' \
    -d'{
        "companyKey": "your-company-secret-key",
        "email": "john.doe@example.com",
        "emailVerified": true,
        "password": "SecurePass123!",
        "firstName": "John",
        "lastName": "Doe",
        "rights": [
            "call_center_operator",
            "administrator",
            "operator"
    ]
}'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "email": "john.doe@example.com",
  "emailVerified": true,
  "password": "SecurePass123!",
  "firstName": "John",
  "lastName": "Doe",
  "rights": [
        "call_center_operator",
        "administrator",
        "operator"
    ]
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
    "result": "68243e94540d1e5fe6c04a0f"
}
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

*invalidCompanyKey:*

```json
{
  "argumentError": "invalid-company-key"
}
```

*invalidEmailFormat:*

```json
{
  "argumentError": "invalid-email-format"
}
```

*passwordTooShort*

```json
{
  "argumentError": "password-too-short"
}
```

*passwordIsNotString*

```json
{
  "internalError": Illegal arguments: number, string"
}
```

*invalidRights*

```json
{
  "argumentError": "invalid-rights"
}
```

*userAlreadyExists:*

```json
{
  "argumentError": "user-already-exists"
}
```

</details>

<details>

<summary>delete-user - Видалити користувача</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/delete-user</mark>](https://external-api.identomat.com/delete-user)

**Опис:**

Видаляє користувача з платформи Identomat (Manage).

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `userId` *(string, обов'язковий)* - Унікальний ідентифікатор користувача.

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

{% code overflow="wrap" %}

```bash
curl -X POST 'https://external-api.identomat.com/delete-user' \
    -H 'Content-Type: application/json' \
    -d'{
        "companyKey": "your-company-secret-key",
        "userId": "68243e94540d1e5fe6c04a0f"
    ]
}'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "userId": "68243e94540d1e5fe6c04a0f"
}
```

**Приклади результату:**

*за замовчуванням:*

```
{ }
```

*wrongParameters:*

```json
{
  "argumentError": "wrong-parameters"
}
```

*invalidCompanyKey:*

```json
{
  "argumentError": "invalid-company-key"
}
```

*userNotFound:*

```json
{
  "argumentError": "user-not-found"
}
```

</details>

<details>

<summary>get-session-config - Отримати конфігурацію сесії</summary>

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/get-session-config</mark>](https://external-api.identomat.com/get-session-config)

**Опис:**

Цей ендпоінт отримує деталі конфігурації для конкретної конфігурації сесії на основі наданого ID конфігурації сесії.

**Параметри:**

* `companyKey` *(string, обов'язковий)* - Секретний ключ компанії.
* `sessionConfigId` *(string, обов'язковий)* – Унікальний ідентифікатор конфігурації сесії.

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/get-session-config \
    -H 'Content-Type: application/json' \
    -d '{
        "companyKey":"your-company-secret-key",
        "sessionConfigId":"6162636465666768696a6b6c"
}'
```

{% endcode %}

**Приклади параметрів запиту:**

```json
{
  "companyKey": "your-company-secret-key",
  "sessionConfigId": "6162636465666768696a6b6c"
}
```

**Приклади результату:**

*за замовчуванням:*

```json
{
  "result": {
    "id": "679c74e4d9725987e3879265",
    "name": "Configuration Template",
    "general": {
        "language": "en",
        "sessionLifetime": 15
        },
    "steps": [
      {
        "title": {
          "en": "ID Verification"
        },
        "type": "identity-document",
        "key": "select_document_id",
        "flags": {
          "documentTypes": [
            "id",
            "passport",
            "driver_license",
            "residence_permit"
          ]
        }
      },
      {
        "title": {
          "en": "Liveness Check"
        },
        "type": "liveness",
        "key": "liveness",
        "flags": {
          "liveness": true,
          "maxLivenessAttempts": 3
        }
      }
    ]
  }
}

```

*wrongParameters:*

```
{
    "argumentError": "wrong-parameters"
}
```

</details>

### Обробка зображення

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

<details>

<summary>card/front/ - Лицьова сторона ID-картки</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/card/front/</mark>](https://widget.identomat.com/external-api/card/front/)

**Параметри:**

* `company_key` *(string, обов'язковий)* - Секретний ключ компанії.
* `image` *(file, обов'язковий)* – Файл зображення JPEG для завантаження.

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

{% code overflow="wrap" %}

```bash
curl https://widget.identomat.com/external-api/card/front/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'image=@{example_image.jpg}'
```

{% endcode %}

**Приклади результату:**

*за замовчуванням:*

```json
{
    "Given_Names_en_US": "JOHN",
    "Surname_en_US": "DOE",
    "citizenship": "USA",
    "Sex_en_US": "M",
    "Personal_Number_en_US": "1234567890",
    "Date_of_Birth_en_US": "1/1/1990",
    "Date_of_Expiry_en_US": "1/1/2030",
    "Document_Number_en_US": "USA1234567",
    "Issuing_State_Code_en_US": "USA",
    "Date_of_Birth_ISO": "1990-01-01T00:00:00.000Z",
    "Date_of_Expiry_ISO": "2030-01-01T00:00:00.000Z",
    "requestId": "abcdef1234567890abcdef1234567890",
    "person": {
        "first_name": "JOHN",
        "last_name": "DOE",
        "birthday": "1/1/1990",
        "birthday_time": "1990-01-01T00:00:00.000Z",
        "age": 34,
        "citizenship": "USA",
        "document_number": "USA1234567",
        "document_expires": "1/1/2030",
        "document_expires_time": "2030-01-01T00:00:00.000Z",
        "personal_number": "1234567890",
        "issuing_state": "USA",
        "sex": "M"
    }
}
```

</details>

<details>

<summary>card/back/ - Зворотна сторона ID-картки</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/card/back/</mark>](https://widget.identomat.com/external-api/card/back/)

**Параметри:**

* `company_key` (*string, обов'язковий)* - Секретний ключ компанії.
* `image` *(file, обов'язковий)* – Файл зображення JPEG для завантаження.

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

{% code overflow="wrap" %}

```bash
curl https://widget.identomat.com/external-api/card/back/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'image=@{example-image.jpg}'
```

{% endcode %}

**Приклади результату:**

*за замовчуванням:*

```json
{
    "Date_of_Issue_en_US": "6/28/2021",
    "Issuing_State_Code_en_US": "USA",
    "Place_of_Birth_en_US": "USA",
    "Date_of_Issued_ISO": "2021-06-28T00:00:00.000Z",
    "Given_Names_en_US": "JOHN DOE",
    "Surname_en_US": "DOE",
    "Nationality_Code_en_US": "USA",
    "Sex_en_US": "M",
    "Personal_Number_en_US": "1234567890",
    "Date_of_Birth_en_US": "1/1/1990",
    "Date_of_Expiry_en_US": "6/28/2031",
    "Document_Number_en_US": "USA1234567",
    "Nationality_en_US": "USA",
    "Date_of_Birth_ISO": "1990-01-01T00:00:00.000Z",
    "Date_of_Expiry_ISO": "2031-06-28T00:00:00.000Z",
    "mrz": "IDUSA1234567938001085718<<<<\n8001081M2606288USA<<<<<<<<<<<1\nDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<",
    "requestId": "abcdef1234567890abcdef1234567890",
    "person": {
        "first_name": "JOHN DOE",
        "last_name": "DOE",
        "birthday": "1/1/1990",
        "birthday_time": "1990-01-01T00:00:00.000Z",
        "age": 34,
        "birth_place": "USA",
        "nationality": "USA",
        "document_number": "USA1234567",
        "document_issued": "6/28/2021",
        "document_expires": "6/28/2031",
        "document_expires_time": "2031-06-28T00:00:00.000Z",
        "document_issued_time": "2021-06-28T00:00:00.000Z",
        "personal_number": "1234567890",
        "issuing_state": "USA",
        "sex": "M",
        "mrz": "IDUSA1234567938001085718<<<<\n8001081M2606288USA<<<<<<<<<<<1\nDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<"
    }
}
```

</details>

<details>

<summary>license/front/ - Лицьова сторона водійського посвідчення</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/license/front/</mark>](https://widget.identomat.com/external-api/license/front/)

**Параметри:**

* `company_key` (*string, обов'язковий)* - Секретний ключ компанії.
* `image` *(file, обов'язковий)* – Файл зображення JPEG для завантаження.

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

{% code overflow="wrap" %}

```bash
curl https://widget.identomat.com/external-api/license/front/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'image=@{example_image.jpg}'
```

{% endcode %}

**Приклади результату:**

*за замовчуванням:*

```json
{
    "Given_Names_en_US": "John",
    "Surname_en_US": "Doe",
    "Given_Names_ka_GE": "ჯონ",
    "Surname_ka_GE": "დო",
    "Personal_Number_en_US": "1234567890",
    "Date_of_Birth_en_US": "1/1/1985",
    "Date_of_Issue_en_US": "5/15/2015",
    "Document_Number_en_US": "ID1234567",
    "Issuing_State_Code_en_US": "USA",
    "Place_of_Birth_en_US": "Los Angeles",
    "Authority_en_US": "Department of Motor Vehicles",
    "Date_of_Birth_ISO": "1985-01-01T00:00:00.000Z",
    "Date_of_Issued_ISO": "2015-05-15T00:00:00.000Z",
    "Address_en_US": "456 Main St, Los Angeles, CA 90001",
    "Local_Address_en_US": "456 Main St, Los Angeles, CA 90001",
    "localAuthority": "Department of Motor Vehicles",
    "Drivers_License_Class_en_US": "C",
    "requestId": "a1b2c3d4e5f67890",
    "person": {
        "local_first_name": "ჯონ",
        "local_last_name": "დო",
        "first_name": "John",
        "last_name": "Doe",
        "birthday": "1/1/1985",
        "birthday_time": "1985-01-01T00:00:00.000Z",
        "age": 40,
        "birth_place": "Los Angeles",
        "document_number": "ID1234567",
        "document_issued": "5/15/2015",
        "document_issued_time": "2015-05-15T00:00:00.000Z",
        "personal_number": "1234567890",
        "authority": "Department of Motor Vehicles",
        "local_authority": "Department of Motor Vehicles",
        "issuing_state": "USA",
        "address": "456 Main St, Los Angeles, CA 90001",
        "local_address": "456 ქუჩა, ლოს ანჯელესი, CA 90001"
    }
}
```

</details>

<details>

<summary>license/back/ - Зворотна сторона водійського посвідчення</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/license/back/</mark>](https://widget.identomat.com/external-api/license/back/)

**Параметри:**

* `company_key` (*string, обов'язковий)* - Секретний ключ компанії.
* `image` *(file, обов'язковий)* – Файл зображення JPEG для завантаження.

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

{% code overflow="wrap" %}

```bash
curl https://widget.identomat.com/external-api/license/back/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'image=@{example_image.jpg}'
```

{% endcode %}

**Приклади результату:**

*за замовчуванням:*

```json
{
    "Issuing_State_Code_en_US": "USA",
    "requestId": "262f6ee39992e0a61769c5cc13b2f092",
    "person": {
        "issuing_state": "USA"
    }
}
```

</details>

<details>

<summary>residence/front/ - Лицьова сторона посвідки на проживання</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/residence/front/</mark>](https://widget.identomat.com/external-api/residence/front/)

**Параметри:**

* `company_key` (*string, обов'язковий)* - Секретний ключ компанії.
* `image` *(file, обов'язковий)* – Файл зображення JPEG для завантаження.

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

{% code overflow="wrap" %}

```bash
curl https://widget.identomat.com/external-api/residence/front/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'image=@{example_image.jpg}'
```

{% endcode %}

**Приклади результату:**

*за замовчуванням:*

```json
{
    "Given_Names_en_US": "John",
    "Surname_en_US": "Doe",
    "Nationality_Code_en_US": "USA",
    "Sex_en_US": "M",
    "Date_of_Birth_en_US": "5/15/1985",
    "Date_of_Expiry_en_US": "12/31/2030",
    "Document_Number_en_US": "D12345678",
    "Nationality_en_US": "USA",
    "Issuing_State_Code_en_US": "USA",
    "Date_of_Birth_ISO": "1985-05-15T00:00:00.000Z",
    "Date_of_Expiry_ISO": "2030-12-31T00:00:00.000Z",
    "requestId": "1234567890abcdef1234567890abcdef",
    "person": {
        "first_name": "John",
        "last_name": "Doe",
        "birthday": "5/15/1985",
        "birthday_time": "1985-05-15T00:00:00.000Z",
        "age": 40,
        "nationality": "USA",
        "document_number": "D12345678",
        "document_expires": "12/31/2030",
        "document_expires_time": "2030-12-31T00:00:00.000Z",
        "issuing_state": "USA",
        "sex": "M"
    }
}
```

</details>

<details>

<summary>residence/back/ - Зворотна сторона посвідки на проживання</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/residence/back/</mark>](https://widget.identomat.com/external-api/residence/back/)

**Параметри:**

* `company_key` (*string, обов'язковий)* - Секретний ключ компанії.
* `image` *(file, обов'язковий)* – Файл зображення JPEG для завантаження.

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

{% code overflow="wrap" %}

```bash
curl https://widget.identomat.com/external-api/residence/back/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'image=@{example_image.jpg}'
```

{% endcode %}

**Приклади результату:**

*за замовчуванням:*

```json
{
    "Date_of_Issue_en_US": "7/1/2020",
    "Issuing_State_Code_en_US": "ITA",
    "Place_of_Birth_en_US": "CITTA",
    "Date_of_Issued_ISO": "2020-07-01T00:00:00.000Z",
    "Given_Names_en_US": "John",
    "Surname_en_US": "Doe",
    "Nationality_Code_en_US": "USA",
    "Sex_en_US": "M",
    "Date_of_Birth_en_US": "5/15/1985",
    "Date_of_Expiry_en_US": "12/31/2030",
    "Document_Number_en_US": "D12345678",
    "Nationality_en_US": "USA",
    "Date_of_Birth_ISO": "1985-05-15T00:00:00.000Z",
    "Date_of_Expiry_ISO": "2030-12-31T00:00:00.000Z",
    "mrz": "P<USADOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<\nD12345678USA850515M3031232<<<<<<<<<<<<<<06",
    "requestId": "5924aa4e44eb394f7cd2377568c21859",
    "person": {
        "first_name": "John",
        "last_name": "Doe",
        "birthday": "5/15/1985",
        "birthday_time": "1985-05-15T00:00:00.000Z",
        "age": 40,
        "birth_place": "CITTA",
        "nationality": "USA",
        "document_number": "D12345678",
        "document_issued": "7/1/2020",
        "document_expires": "12/31/2030",
        "document_expires_time": "2030-12-31T00:00:00.000Z",
        "document_issued_time": "2020-07-01T00:00:00.000Z",
        "issuing_state": "ITA",
        "sex": "M",
        "mrz": "P<USADOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<\nD12345678USA850515M3031232<<<<<<<<<<<<<<06"
    }
}
```

</details>

<details>

<summary>passport/ - Сторінка з фото паспорта</summary>

**URL:**

[<mark style="color:blue;">https://widget.identomat.com/external-api/passport/</mark>](https://widget.identomat.com/external-api/passport/)

**Параметри:**

* `company_key` (*string, обов'язковий)* - Секретний ключ компанії.
* `image` *(file, обов'язковий)* – Файл зображення JPEG для завантаження.

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

{% code overflow="wrap" %}

```bash
curl https://widget.identomat.com/external-api/passport/ \
    -F 'company_key={your-company-secret-key}' \
    -F 'image=@{example_image.jpg}'
```

{% endcode %}

**Приклад результату:**

*за замовчуванням:*

```json
{
    "mrzData": {
        "Given_Names_en_US": "JOHN",
        "Surname_en_US": "DOE",
        "Nationality_Code_en_US": "USA",
        "Sex_en_US": "M",
        "Date_of_Birth_en_US": "1/1/1990",
        "Date_of_Expiry_en_US": "1/1/2030",
        "Document_Number_en_US": "USA1234567",
        "Nationality_en_US": "USA",
        "Issuing_State_Code_en_US": "USA",
        "Date_of_Birth_ISO": "1990-01-01T00:00:00.000Z",
        "Date_of_Expiry_ISO": "2030-01-01T00:00:00.000Z",
        "mrz": "P<USADOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<\nUSA1234567USA9001019M3001019<<<<<<<<<<<<<<00"
    },
    "visualData": {
        "Given_Names_en_US": "JOHN",
        "Surname_en_US": "DOE",
        "Nationality_Code_en_US": "USA",
        "Sex_en_US": "M",
        "Personal_Number_en_US": "1234567890",
        "Date_of_Birth_en_US": "1/1/1990",
        "Date_of_Expiry_en_US": "1/1/2030",
        "Date_of_Issue_en_US": "1/1/2020",
        "Document_Number_en_US": "USA1234567",
        "Nationality_en_US": "USA",
        "Issuing_State_Code_en_US": "USA",
        "Place_of_Birth_en_US": "NEW YORK",
        "Authority_en_US": "USA AUTHORITY",
        "Date_of_Birth_ISO": "1990-01-01T00:00:00.000Z",
        "Date_of_Expiry_ISO": "2030-01-01T00:00:00.000Z",
        "Date_of_Issued_ISO": "2020-01-01T00:00:00.000Z"
    },
    "requestId": "1234567890abcdef1234567890abcdef",
    "person": {
        "first_name": "JOHN",
        "last_name": "DOE",
        "birthday": "1/1/1990",
        "birthday_time": "1990-01-01T00:00:00.000Z",
        "age": 34,
        "birth_place": "NEW YORK",
        "nationality": "USA",
        "document_number": "USA1234567",
        "document_issued": "1/1/2020",
        "document_expires": "1/1/2030",
        "document_expires_time": "2030-01-01T00:00:00.000Z",
        "document_issued_time": "2020-01-01T00:00:00.000Z",
        "personal_number": "1234567890",
        "authority": "USA AUTHORITY",
        "issuing_state": "USA",
        "sex": "M",
        "status": "FIELDS_MISMATCH",
        "mrz": "P<USADOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<\nUSA1234567USA9001019M3001019<<<<<<<<<<<<<<00"
    }
}
```

</details>

### Додаткова обробка

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

<details>

<summary>compare-faces/ - Отримати бал схожості для двох облич</summary>

Мінімальний рекомендований розмір обличчя на зображенні — **80 пікселів**. Якщо розмір обличчя становить **65-79 пікселів**, буде повернуто код помилки разом із балом схожості.

**URL:**

[<mark style="color:blue;">https://external-api.identomat.com/compare-faces</mark>](https://external-api.identomat.com/compare-faces)

**Параметри:**

* `companyKey` (string, обов'язковий) - Секретний ключ компанії.
* `face1` *(file, обов'язковий)* - Файл зображення JPEG для обличчя1
* `face2` *(file, обов'язковий)* - Файл зображення JPEG для обличчя2

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

{% code overflow="wrap" %}

```bash
curl -X POST https://external-api.identomat.com/compare-faces \
    -F 'companyKey={your-company-secret-key}' \
    -F 'face1=@{example_face1.jpg}' \
    -F 'face2=@{example_face2.jpg}'
```

{% endcode %}

**Приклади результату:**

*за замовчуванням:*

```json
{
    "result": {
        "similarity": 0.9399788229619534,
        "face1Statuses": [],
        "face2Statuses": []
    }
}
```

*error:*

```json
{
    "result": {
        "similarity": null,
        "face1Statuses": [
            "FACE_FAR_AWAY"
        ],
        "face2Statuses": []
    }
}
```

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

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

```
GET https://docs.identomat.com/identomat-documentation-ukr/dovidnik-api.md?ask=<question>&goal=<endgoal>
```

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

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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