Перейти к содержанию

KYB — заявители-компании и их UBO

Пять эндпоинтов на партнёрской стороне KYB. Все привязаны к externalUserId родительской компании.

Создание заявителя-компании

POST /v1/applicants принимает полный KYB-блок идентификации вместе с индивидуальными полями. Передавайте type: "company" + всё, что у вас уже есть; backend молча отбрасывает поля, которые шаг company_data выбранного уровня не включает, а остальное собирает SDK.

curl -X POST 'https://api.compliance.example/v1/applicants' \
  -H 'X-Api-Key: pk_live_...' -H 'X-Api-Secret: ...' \
  -H 'X-Environment: production' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalUserId": "acme-corp",
    "type": "company",
    "verificationLevelName": "KYB_STANDARD",
    "companyName": "ACME LLC",
    "registrationNumber": "12345/789",
    "legalForm": "LLC",
    "incorporationDate": "2018-04-02",
    "registeredAddress": "1 Market St, San Francisco, CA",
    "country": "USA",
    "email": "info@acme.com",
    "phone": "+1 555 0199"
  }'

email и phone у заявителя-компании — это контакт компании (общий ящик / коммутатор). Личные email и телефон контактного лица собираются, когда оно спавнится в собственный KYC-подзаявитель через spawn-kyc.

Чтобы узнать, какие поля реально собирает уровень (и какие из них обязательные), смотрите GET /v1/levels/{levelName} — массивы companyDataFields / companyRequiredFields / companyRequiredDocuments точно говорят, что предзаполнять.

Важно — поля, переданные партнёром, блокируются. Каждое значение, которое вы передаёте при создании, становится неизменяемым со стороны SDK: input в форме рендерится как disabled, а POST /api/v1/sdk/personal-info отказывается мутировать поле. Снять блокировку можно только PATCH-ем поля через публичный API. Подробнее — в разделе Блокировка полей гайда «Уровни верификации».

Чтение компании

GET /v1/applicants/{externalUserId}/company-info

Структурированный блок KYB-идентификации (без UBO — у них свой эндпоинт). 400 для индивидуального заявителя.

{
  "externalUserId": "acme-corp",
  "companyName": "ACME LLC",
  "registrationNumber": "12345/789",
  "legalForm": "llc",
  "incorporationDate": "2018-04-02",
  "registeredAddress": "1 Market St, San Francisco, CA",
  "country": "USA",
  "status": "active",
  "riskLevel": "low",
  "verificationLevelName": "KYB_STANDARD",
  "createdAtUtc": "...",
  "updatedAtUtc": "..."
}

GET /v1/applicants/{externalUserId}/company-structure

Сводка по UBO: четыре флага негативной декларации + счётчики по ролям + сводка по «развёрнутым» дочерним заявителям. Достаточно, чтобы показать «KYB ждёт N человек» без перечисления каждого UBO.

{
  "externalUserId": "acme-corp",
  "hasNoUbos": false,
  "hasNoShareholders": false,
  "hasNoDirectors": false,
  "hasNoRepresentatives": false,
  "counts": {
    "total": 3,
    "ubos": 2,
    "directors": 2,
    "shareholders": 0,
    "representatives": 0,
    "spawned": 3,
    "completed": 2,
    "rejected": 0,
    "pending": 1
  },
  "allChildrenComplete": false,
  "lastChildCompletedAtUtc": "2026-06-07T11:02:00Z"
}

Счётчики ролей учитывают multi-role merge — одна строка с roles=["ubo","director"] попадает в обе категории.

Изменение компании

PATCH /v1/applicants/{externalUserId}/company-info

Частичное обновление KYB-полей. Передавайте только то, что меняете.

country отклоняется с 409, пока идёт верификация — применимость уровня привязана к стране, незаметная замена могла бы направить заявителя в неподходящий уровень. Если смена действительно нужна — сначала Reset заявителя.

curl -X PATCH 'https://api.compliance.example/v1/applicants/acme-corp/company-info' \
  -H 'X-Api-Key: pk_live_...' -H 'X-Api-Secret: ...' \
  -H 'X-Environment: production' \
  -H 'Content-Type: application/json' \
  -d '{ "legalForm": "ltd", "registeredAddress": "10 Downing St, London" }'

Изменение одной строки UBO

PATCH /v1/applicants/{externalUserId}/ubos/{uboIndex}

uboIndex — индекс с нуля в массиве ubos[]. Заблокированные поля тихо игнорируются: linkedApplicantId, source, verificationLinkUrl, verificationLinkExpiresAtUtc.

Правка fullName / dateOfBirth уже «развёрнутого» UBO вернёт identityChangedAfterSpawn=true, чтобы оператор мог при желании проверить переименование.

curl -X PATCH 'https://api.compliance.example/v1/applicants/acme-corp/ubos/0' \
  -H 'X-Api-Key: pk_live_...' -H 'X-Api-Secret: ...' \
  -H 'X-Environment: production' \
  -H 'Content-Type: application/json' \
  -d '{ "ownershipPercent": 51, "roles": ["ubo", "director"] }'

Запуск верификации для UBO

POST /v1/applicants/{externalUserId}/ubos/{uboIndex}/spawn-kyc

Создаёт дочернего заявителя для UBO по uboIndex и сразу выпускает свежую SDK-короткую ссылку. Идемпотентен по linkedApplicantId — повторный вызов вернёт alreadyLinked: true с тем же childApplicantId и новой ссылкой.

curl -X POST 'https://api.compliance.example/v1/applicants/acme-corp/ubos/0/spawn-kyc' \
  -H 'X-Api-Key: pk_live_...' -H 'X-Api-Secret: ...' \
  -H 'X-Environment: production' \
  -H 'Content-Type: application/json' \
  -d '{ "ttlDays": 14, "lang": "ru", "theme": "dark", "returnUrl": "https://acme.com/ubo-done" }'

{
  "uboIndex": 0,
  "childApplicantId": "0a1b2c3d-...",
  "childExternalUserId": "app_a7c4f9e1b3",
  "alreadyLinked": false,
  "sdkLink": {
    "url": "https://sdk.compliance.example/l/x9k2m4",
    "shortCode": "x9k2m4",
    "expiresAtUtc": "2026-06-21T...",
    "token": "eyJhbGciOi..."
  }
}

Отправляете sdkLink.url UBO, он проходит KYC, прилетает вебхук дочернего заявителя; KybParentFanIn закрывает родительский KYB, когда все дочерние дойдут до терминального состояния.

Ограничение по ключу — PartnerApi:SpawnRateLimitPerHour (по умолчанию 1000/час). 429 + Retry-After при превышении.

POST /v1/applicants/{externalUserId}/ubos/{uboIndex}/regenerate-link

Ссылка истекла или был мягкий отказ — выпускаете свежую ссылку без создания нового дочернего заявителя. Заодно очищается состояние rejected/failed на дочерней сессии.

Ограничение: 5 регенераций на одну строку UBO за 24 часа (настраивается через PartnerApi:RegenerateLinkPerChildCapPer24h). 429 + Retry-After при превышении.

curl -X POST 'https://api.compliance.example/v1/applicants/acme-corp/ubos/0/regenerate-link' \
  -H 'X-Api-Key: pk_live_...' -H 'X-Api-Secret: ...' \
  -H 'X-Environment: production' \
  -H 'Content-Type: application/json' \
  -d '{ "ttlDays": 30, "returnUrl": "https://acme.com/done" }'
Что вам нужно… Эндпоинт
Первая KYC для UBO spawn-kyc
Повторная попытка уже «развёрнутого» UBO regenerate-link
Проверить, готов ли UBO company-structure → блок counts
Поправить строку UBO (опечатка, роль) PATCH /ubos/{uboIndex}
Обновить саму компанию PATCH /company-info