AML API: запуск проверок

POST kyc/checks/run

Описание

Запускает проверки физического лица по переданным данным и сразу возвращает runId. Метод асинхронный: результата в ответе нет, он забирается методом POST kyc/checks/result.

Формат запроса

HTTP метод: POST
URL: kyc/checks/run
Тип контента: application/json
Авторизация: обязательна (токен в поле token тела или в заголовке token)

Тело запроса (JSON)

Поле	Тип	Обязательный	Описание
token	string	✅	Постоянный токен доступа. При временном токене — в заголовке `token`, тогда в теле не нужен
person	object	✅	Данные для проверки; `lastName` и `firstName` обязательны
checkers	string[]	❌	Какие проверки запустить. Поле опущено — запускаются все проверки, разрешённые группе

Данные внутри person передаются наборами: набор передан целиком — проверки этого набора работают, набора нет — они возвращают пропуск.

Наборы данных

Набор	Поля	Замечание
Паспорт РФ	`passport.series`, `passport.number`, `passport.issueDate` + ФИО и дата рождения	Основной набор, около 95 % обращений
Водительское удостоверение	`driverLicense.series`, `driverLicense.number`, `driverLicense.issueDate`	Действительность ВУ
ФИО и дата рождения	`lastName`, `firstName`, `middleName`, `birthDate`	Минимальный набор для поиска по реестрам
СНИЛС	`snils` (11 цифр)	Принимается и передаётся источнику
Адрес регистрации	`address.full`, `address.type` (`reg` — жительство, `fact` — пребывание)	Принимается и передаётся источнику
Телефон	`phone` — мобильный номер РФ: 10 цифр или 11, начиная с 7 или 8; разделители и `+` в начале отбрасываются	Для проверок номера телефона (принадлежность, активность, возраст номера, подтверждение возраста)
ИНН	`inn` (12 цифр)	Необязателен — проверки определяют ИНН по паспорту сами (нужно отчество)

Разделители в номерах (пробелы, дефисы) убирать не нужно. Даты принимаются в форматах YYYY-MM-DD и DD.MM.YYYY. Проверка, которой не хватило данных, попадает в прогон и возвращает outcome: skipped с перечислением недостающего в missingInputs — это не ошибка и не тарифицируется.

Пример запроса (cURL)

curl -X POST "https://api.neuro-vision.ru/v1/kyc/checks/run" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<permanent-token>",
    "person": {
      "lastName": "Иванов",
      "firstName": "Иван",
      "middleName": "Иванович",
      "birthDate": "1985-03-15",
      "gender": "M",
      "passport": { "series": "4509", "number": "123456", "issueDate": "2010-06-20", "issuerCode": "770-001" },
      "driverLicense": { "series": "7799", "number": "123456", "issueDate": "15.03.2020" },
      "snils": "11223344595",
      "inn": "771234567890",
      "address": { "full": "119991, г. Москва, ул. Ленина, д. 1, кв. 2", "type": "reg" }
    },
    "checkers": ["insolvencyStatus", "debtBurden"]
  }'

Ответ

Поле	Тип	Описание
runId	string	Идентификатор запуска для `kyc/checks/result`
checksStatus	string	Всегда `pending`
pending	number	Сколько проверок запущено
checkers	string[]	Какие проверки запущены

Состав проверок фиксируется в момент запуска: позже к запуску ничего не добавляется.

Успех (200 OK)

{
  "runId": "523c8284-ad9e-11ef-9be1-b8ccad474166",
  "checksStatus": "pending",
  "pending": 2,
  "checkers": ["insolvencyStatus", "debtBurden"],
  "responseTime": "2026-07-28T10:00:00.000Z"
}

Ошибка — неизвестный checker (400)

{
  "status": "error",
  "message": "unknown or not allowed checkers",
  "unknown": ["insolvencyStatuz"],
  "notAllowed": []
}

Ошибки

Код	Тело	Когда
400	`invalid schema` + details	Тело не соответствует схеме
400	`person.lastName and person.firstName are required`	Нет фамилии или имени
400	`unknown or not allowed checkers` (+ `unknown`, `notAllowed`)	Среди `checkers` есть неизвестные или не разрешённые группе идентификаторы
400	`person.phone must be a Russian number: 10 digits, or 11 starting with 7 or 8`	Номер телефона не похож на мобильный номер РФ
400	`person.snils must be 11 digits with valid check digits`	В СНИЛС не 11 цифр или не сходится контрольное число
400	`checkers must not be empty — omit the field to run every allowed check`	Передан пустой массив `checkers` (опустите поле, чтобы запустить все)
400	`no checks are allowed for this account`	Группе не разрешена ни одна проверка
401	`access denied`	Нет токена или токен не действует
500	`internal error`	Внутренняя ошибка; повторите запрос позже

Неизвестный идентификатор не отбрасывается молча: иначе опечатка превратилась бы в прогон без нужной проверки.