Перейти к содержимому
Справочник API Получить API-ключи

Справочник · Глава 14

Справочник API

Все эндпоинты, вебхуки и модели — автоматически из спецификации OpenAPI.

API платформы KYC

Версия v1
Базовый URL https://kyc.goxost.net/api/v1

REST API для клиентов платформы. Ваш бэкенд создаёт заявителя, открывает сессию проверки и передаёт конечному пользователю url сессии (hosted-сценарий) или token (SDK). Результат приходит вебхуком (verification.completed / verification.on_hold); полный результат получите через GET /verifications/{id}.

Соглашения

  • JSON, UTF-8. Всё время указывается в ISO 8601 UTC (2026-11-07T10:00:00Z). Баллы — числа с плавающей точкой в диапазоне 0..1.
  • ID: apl_… заявитель, ses_… сессия, ver_… проверка, whk_… вебхук, whd_… доставка, evt_… событие.
  • Ключ видит только свой аккаунт и окружение (sandbox для sk_test_…, live для sk_live_…). Всё остальное возвращает 404 not_found. Один и тот же external_id в двух окружениях — это два разных заявителя.
  • Каждый ответ содержит X-Request-Id: req_… (при ошибке совпадает с error.request_id).
  • Лимит частоты: 600 запросов в минуту на ключ (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After при 429).
  • Идемпотентность: запросы на запись (POST, PATCH, DELETE) принимают Idempotency-Key (8–64 символа, [A-Za-z0-9_-]). Тот же ключ в течение 24 ч возвращает тот же ответ с Idempotent-Replayed: true. Повтор ключа с другим телом → 409 idempotency_conflict; пока первый запрос ещё выполняется → 409 conflict. Ответы 5xx не сохраняются. Некорректный ключ → 400 bad_request.
  • Тестовый режим: с sk_test_ результат имитируется по суффиксу external_id: -expired (RED retry, DOC_EXPIRED), -mismatch (RED final, FACE_MISMATCH), -hold (ON_HOLD, PEP_MATCH), -sanctions (RED final, SANCTIONS_MATCH), -duplicate (RED final, DUPLICATE от проверки duplicate; в тестовом режиме без details.applicant_ids), -underage (RED final, UNDERAGE), -age-unknown (ON_HOLD, AGE_UNKNOWN; только в сценарии с checks.age_only), -recapture (ON_HOLD, DOC_SCREEN_RECAPTURE от проверки подлинности документа doc_fraud), всё остальное → GREEN. Тестовый режим не учитывается в месячном лимите.

Аутентификация

Authorization: Bearer sk_live_… (боевой режим) или sk_test_… (тестовый режим). Храните ключи на своём сервере; в браузер передавайте только токен сессии. Заблокированный аккаунт получает 403 forbidden.

Ошибки

400 bad_request, validation_failed · 401 unauthenticated · 403 forbidden · 404 not_found · 409 conflict, idempotency_conflict · 413 file_too_large (тело запроса больше лимита сервера) · 422 unprocessable · 429 rate_limited, plan_limit_reached · 5xx internal_error, aml_unavailable.

{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}

Заявители

Проверяемый человек. У заявителя может быть только одна активная сессия.

get /api/v1/applicants

Список заявителей

Сначала новые, курсорная пагинация.

Параметры

  • external_id string query
  • status ApplicantStatus query
  • decision Decision query
  • flow string query
    Ключ сценария.
  • created_from string (date-time) query
  • created_to string (date-time) query
  • limit integer query
  • cursor string query
    Непрозрачный next_cursor из предыдущей страницы.

Ответы

200 Страница заявителей. object
{
    "data": [
        {
            "id": "apl_01j9…",
            "external_id": "user-8812",
            "flow": "basic-kyc",
            "locale": "uz",
            "status": "init",
            "decision": "GREEN",
            "risk_score": 0.5,
            "last_verification_id": "string",
            "metadata": {},
            "purpose": "string",
            "valid_until": "2026-11-07T10:00:00Z",
            "created_at": "2026-11-07T10:00:00Z",
            "updated_at": "2026-11-07T10:00:00Z",
            "identity": {
                "verification_id": "string",
                "verified_at": "2026-11-07T10:00:00Z",
                "document": {
                    "type": "string",
                    "country": "string",
                    "data": {
                        "first_name": "ANNA MARIA",
                        "last_name": "ERIKSSON",
                        "middle_name": null,
                        "full_name": "ANNA MARIA ERIKSSON",
                        "birth_date": null,
                        "place_of_birth": null,
                        "sex": "M",
                        "nationality": "UTO",
                        "document_type": "passport",
                        "document_subtype": "P",
                        "issuing_country": "UTO",
                        "number": "L898902C3",
                        "personal_number": null,
                        "personal_number_type": "JShShIR (PINFL)",
                        "personal_number_valid": null,
                        "issue_date": null,
                        "expiry_date": null,
                        "issuing_authority": null,
                        "address": null,
                        "series": null,
                        "division_code": null,
                        "age": null,
                        "is_expired": null,
                        "days_to_expiry": null,
                        "names": null,
                        "fields": null
                    }
                }
            }
        }
    ],
    "next_cursor": "string"
}
400 validation_failed (ошибки полей в error.fields) или bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
429 rate_limited Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/applicants

Создать заявителя

Отправляет событие applicant.created.

Параметры

  • Idempotency-Key string header
    Тот же ключ → тот же ответ в течение 24 ч (Idempotent-Replayed: true).

Тело запроса ApplicantCreate

  • external_id string обязательно
    ID пользователя у вас; печатные ASCII-символы, уникален в пределах окружения.
  • flow string
  • locale Locale
  • purpose string | null
    Цель проверки по умолчанию для сессий этого заявителя.
  • metadata object
    Строки ключ/значение без персональных данных, ≤ 2 КБ в виде JSON.
  • email —
    Пока не принимается: непустое значение → 400 validation_failed (fields.email). Не сохраняется и не возвращается (зашифрованное хранение контактов появится позже).
  • phone —
    Пока не принимается: непустое значение → 400 validation_failed (fields.phone). Не сохраняется и не возвращается.
{
    "external_id": "user-8812",
    "flow": "basic-kyc",
    "locale": "uz",
    "metadata": {
        "plan": "gold"
    }
}

Ответы

201 Создано. Applicant
{
    "id": "apl_01j9…",
    "external_id": "user-8812",
    "flow": "basic-kyc",
    "locale": "uz",
    "status": "init",
    "decision": "GREEN",
    "risk_score": 0.5,
    "last_verification_id": "string",
    "metadata": {},
    "purpose": "string",
    "valid_until": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "updated_at": "2026-11-07T10:00:00Z",
    "identity": {
        "verification_id": "string",
        "verified_at": "2026-11-07T10:00:00Z",
        "document": {
            "type": "string",
            "country": "string",
            "data": {
                "first_name": "ANNA MARIA",
                "last_name": "ERIKSSON",
                "middle_name": "string",
                "full_name": "ANNA MARIA ERIKSSON",
                "birth_date": "1994-03-12",
                "place_of_birth": "string",
                "sex": "M",
                "nationality": "UTO",
                "document_type": "passport",
                "document_subtype": "P",
                "issuing_country": "UTO",
                "number": "L898902C3",
                "personal_number": "string",
                "personal_number_type": "JShShIR (PINFL)",
                "personal_number_valid": true,
                "issue_date": "1994-03-12",
                "expiry_date": "1994-03-12",
                "issuing_authority": "string",
                "address": "string",
                "series": "string",
                "division_code": "string",
                "age": 0,
                "is_expired": true,
                "days_to_expiry": 0,
                "names": {
                    "mrz": {},
                    "viz": {},
                    "native": {}
                },
                "fields": {}
            }
        }
    }
}
400 validation_failed (ошибки полей в error.fields) или bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — external_id уже существует в этом окружении, или ошибка идемпотентности. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
422 unprocessable — неизвестный flow. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
429 rate_limited Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/applicants/{id}

Получить заявителя

Параметры

  • id string path обязательно
  • include string query
    identity добавляет данные документа из последней проверки GREEN (identity). Без него ключа в ответе нет, и зашифрованное хранилище не читается. Каждое чтение фиксируется в журнале аудита (vault.read); у запросов с include свой лимит частоты на ключ (по умолчанию 30/мин).

Ответы

200 Текущий статус и последнее решение. Applicant
{
    "id": "apl_01j9…",
    "external_id": "user-8812",
    "flow": "basic-kyc",
    "locale": "uz",
    "status": "init",
    "decision": "GREEN",
    "risk_score": 0.5,
    "last_verification_id": "string",
    "metadata": {},
    "purpose": "string",
    "valid_until": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "updated_at": "2026-11-07T10:00:00Z",
    "identity": {
        "verification_id": "string",
        "verified_at": "2026-11-07T10:00:00Z",
        "document": {
            "type": "string",
            "country": "string",
            "data": {
                "first_name": "ANNA MARIA",
                "last_name": "ERIKSSON",
                "middle_name": "string",
                "full_name": "ANNA MARIA ERIKSSON",
                "birth_date": "1994-03-12",
                "place_of_birth": "string",
                "sex": "M",
                "nationality": "UTO",
                "document_type": "passport",
                "document_subtype": "P",
                "issuing_country": "UTO",
                "number": "L898902C3",
                "personal_number": "string",
                "personal_number_type": "JShShIR (PINFL)",
                "personal_number_valid": true,
                "issue_date": "1994-03-12",
                "expiry_date": "1994-03-12",
                "issuing_authority": "string",
                "address": "string",
                "series": "string",
                "division_code": "string",
                "age": 0,
                "is_expired": true,
                "days_to_expiry": 0,
                "names": {
                    "mrz": {},
                    "viz": {},
                    "native": {}
                },
                "fields": {}
            }
        }
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
delete /api/v1/applicants/{id}

Удалить заявителя

Сразу же: открытые сессии становятся abandoned, external_id меняется на deleted:{id}, metadata очищается, ключ заявителя в зашифрованном хранилище уничтожается (crypto-shred), файлы и слепые индексы удаляются; реплика в core тоже уничтожается (если core недоступен — повтор каждые 5 минут). Отправляет applicant.deleted (с исходным external_id). После этого запрос заявителя возвращает 404; история проверок сохраняется без персональных данных.

Параметры

  • id string path обязательно
  • Idempotency-Key string header
    Тот же ключ → тот же ответ в течение 24 ч (Idempotent-Replayed: true).

Ответы

202 Удаление запланировано. object
{
    "id": "apl_01j9…",
    "status": "deletion_scheduled"
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/applicants/{id}/reset

Открыть для повторной проверки

Статус → init, решение и балл риска сбрасываются, открытые сессии → abandoned. История сохраняется. Отправляет applicant.reset.

Параметры

  • id string path обязательно
  • Idempotency-Key string header
    Тот же ключ → тот же ответ в течение 24 ч (Idempotent-Replayed: true).

Ответы

200 Сброшенный заявитель. Applicant
{
    "id": "apl_01j9…",
    "external_id": "user-8812",
    "flow": "basic-kyc",
    "locale": "uz",
    "status": "init",
    "decision": "GREEN",
    "risk_score": 0.5,
    "last_verification_id": "string",
    "metadata": {},
    "purpose": "string",
    "valid_until": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "updated_at": "2026-11-07T10:00:00Z",
    "identity": {
        "verification_id": "string",
        "verified_at": "2026-11-07T10:00:00Z",
        "document": {
            "type": "string",
            "country": "string",
            "data": {
                "first_name": "ANNA MARIA",
                "last_name": "ERIKSSON",
                "middle_name": "string",
                "full_name": "ANNA MARIA ERIKSSON",
                "birth_date": "1994-03-12",
                "place_of_birth": "string",
                "sex": "M",
                "nationality": "UTO",
                "document_type": "passport",
                "document_subtype": "P",
                "issuing_country": "UTO",
                "number": "L898902C3",
                "personal_number": "string",
                "personal_number_type": "JShShIR (PINFL)",
                "personal_number_valid": true,
                "issue_date": "1994-03-12",
                "expiry_date": "1994-03-12",
                "issuing_authority": "string",
                "address": "string",
                "series": "string",
                "division_code": "string",
                "age": 0,
                "is_expired": true,
                "days_to_expiry": 0,
                "names": {
                    "mrz": {},
                    "viz": {},
                    "native": {}
                },
                "fields": {}
            }
        }
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Сессии

Одноразовая ссылка или токен SDK для hosted-сценария проверки.

post /api/v1/applicants/{id}/sessions

Создать сессию проверки

Только для заявителя со status = init (иначе 409 conflict; сначала вызовите reset). У заявителя одна активная сессия: при создании новой предыдущая истекает. url открывает hosted-сценарий, token запускает JS/мобильный SDK. В live при исчерпании месячного лимита возвращается 429 plan_limit_reached.

Параметры

  • id string path обязательно
  • Idempotency-Key string header
    Тот же ключ → тот же ответ в течение 24 ч (Idempotent-Replayed: true).

Тело запроса object

  • redirect_url string (uri)
    Кнопка «Вернуться в сервис» после результата.
  • expires_in integer
    Секунды.
  • locale Locale
    По умолчанию — язык заявителя.
  • purpose string | null
    Зачем проводится проверка (отображается в справке). По умолчанию — purpose заявителя, затем цель по умолчанию из профиля бизнеса.
  • contract ContractBinding
    Привязывает проверку к вашему договору с клиентом. Сохраняется только хеш; он включается в подписанную справку.
{
    "redirect_url": "https://shop.uz/kyc/done",
    "expires_in": 1800,
    "locale": "ru",
    "purpose": "Hisob ochish",
    "contract": {
        "reference": "DOG-2026/17",
        "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    }
}

Ответы

201 Создано. object
{
    "id": "ses_01j9…",
    "url": "https://kyc.goxost.net/v/eyJhbGciOiJFZERTQSJ9…",
    "token": "string",
    "expires_at": "2026-11-07T10:00:00Z"
}
400 validation_failed (ошибки полей в error.fields) или bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — заявитель не в статусе init. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
422 unprocessable — сценарий заявителя больше не существует. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
429 plan_limit_reached (месячный лимит боевого режима) или rate_limited. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/sessions/{id}

Получить сессию

Параметры

  • id string path обязательно

Ответы

200 Состояние сессии. Session
{
    "id": "string",
    "applicant_id": "string",
    "status": "created",
    "locale": "uz",
    "flow_version": 0,
    "steps_done": [
        "string"
    ],
    "expires_at": "2026-11-07T10:00:00Z",
    "started_at": "2026-11-07T10:00:00Z",
    "submitted_at": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "purpose": "string",
    "contract": {
        "reference": "string",
        "sha256": "string"
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Проверки

Результаты, ручная проверка решений ON_HOLD и сохранённые изображения лица.

get /api/v1/applicants/{id}/verifications

История проверок заявителя

Сначала новые, не более 100 последних (без пагинации). document.data равно null, если не передан include=document_data: тогда каждая запись читается из зашифрованного хранилища, и каждое чтение фиксируется в журнале аудита (vault.read, с reason). У запросов с include свой лимит частоты на ключ (по умолчанию 30/мин).

Параметры

  • id string path обязательно
  • include string query
  • reason VaultReadReason query

Ответы

200 История. object
{
    "data": [
        {
            "id": "ver_01j9…",
            "applicant_id": "string",
            "session_id": "string",
            "decision": "GREEN",
            "decision_type": "final",
            "reject_labels": [
                "BAD_QUALITY"
            ],
            "risk_score": 0.5,
            "checks": [
                {
                    "name": "document",
                    "status": "pass",
                    "score": 0.5,
                    "labels": [
                        "BAD_QUALITY"
                    ],
                    "details": {
                        "lists": [
                            "OFAC_SDN"
                        ],
                        "matches": [
                            null
                        ],
                        "applicant_ids": [
                            "apl_01j9…"
                        ],
                        "age_over": {
                            "threshold": 18,
                            "result": null
                        }
                    }
                }
            ],
            "document": {
                "type": "id_card",
                "country": "UZB",
                "data": {
                    "first_name": "ANNA MARIA",
                    "last_name": "ERIKSSON",
                    "middle_name": "string",
                    "full_name": "ANNA MARIA ERIKSSON",
                    "birth_date": "1994-03-12",
                    "place_of_birth": "string",
                    "sex": "M",
                    "nationality": "UTO",
                    "document_type": "passport",
                    "document_subtype": "P",
                    "issuing_country": "UTO",
                    "number": "L898902C3",
                    "personal_number": "string",
                    "personal_number_type": "JShShIR (PINFL)",
                    "personal_number_valid": true,
                    "issue_date": "1994-03-12",
                    "expiry_date": "1994-03-12",
                    "issuing_authority": "string",
                    "address": "string",
                    "series": "string",
                    "division_code": "string",
                    "age": 0,
                    "is_expired": true,
                    "days_to_expiry": 0,
                    "names": {
                        "mrz": null,
                        "viz": null,
                        "native": null
                    },
                    "fields": {}
                }
            },
            "summary": {
                "face_match": 0.5,
                "liveness": 0.5,
                "aml": {
                    "status": "pass",
                    "matches": [
                        {
                            "list": "OFAC_SDN",
                            "entry_id": null,
                            "score": null,
                            "matched_on": null
                        }
                    ],
                    "lists": [
                        "OFAC_SDN"
                    ]
                },
                "age_over": {
                    "threshold": 0,
                    "result": true
                }
            },
            "valid_until": "2026-11-07T10:00:00Z",
            "purpose": "string",
            "contract": {
                "reference": "string",
                "sha256": "string"
            },
            "review_deadline_at": "2026-11-07T10:00:00Z",
            "reviewed_by": 0,
            "reviewed_at": "2026-11-07T10:00:00Z",
            "created_at": "2026-11-07T10:00:00Z",
            "completed_at": "2026-11-07T10:00:00Z"
        }
    ]
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/verifications/{id}

Получить результат проверки

document.data расшифровывается из зашифрованного хранилища и возвращается только в этом ответе; каждое чтение записывается в журнал аудита. При хранении none данные доступны 72 ч после результата, затем null (сохраните их у себя); для сессий без хранения — null. В тестовом режиме это синтетический образец документа, соответствующий тестовому сценарию (без чтения из хранилища). В сценариях только с проверкой возраста всегда null.

Параметры

Ответы

200 Полный результат. Verification
{
    "id": "ver_01j9…",
    "applicant_id": "string",
    "session_id": "string",
    "decision": "GREEN",
    "decision_type": "final",
    "reject_labels": [
        "BAD_QUALITY"
    ],
    "risk_score": 0.5,
    "checks": [
        {
            "name": "document",
            "status": "pass",
            "score": 0.5,
            "labels": [
                "BAD_QUALITY"
            ],
            "details": {
                "lists": [
                    "OFAC_SDN"
                ],
                "matches": [
                    {
                        "list": "OFAC_SDN",
                        "entry_id": "string",
                        "score": 0.5,
                        "matched_on": [
                            "name"
                        ]
                    }
                ],
                "applicant_ids": [
                    "apl_01j9…"
                ],
                "age_over": {
                    "threshold": 18,
                    "result": true
                }
            }
        }
    ],
    "document": {
        "type": "id_card",
        "country": "UZB",
        "data": {
            "first_name": "ANNA MARIA",
            "last_name": "ERIKSSON",
            "middle_name": "string",
            "full_name": "ANNA MARIA ERIKSSON",
            "birth_date": "1994-03-12",
            "place_of_birth": "string",
            "sex": "M",
            "nationality": "UTO",
            "document_type": "passport",
            "document_subtype": "P",
            "issuing_country": "UTO",
            "number": "L898902C3",
            "personal_number": "string",
            "personal_number_type": "JShShIR (PINFL)",
            "personal_number_valid": true,
            "issue_date": "1994-03-12",
            "expiry_date": "1994-03-12",
            "issuing_authority": "string",
            "address": "string",
            "series": "string",
            "division_code": "string",
            "age": 0,
            "is_expired": true,
            "days_to_expiry": 0,
            "names": {
                "mrz": {},
                "viz": {},
                "native": {}
            },
            "fields": {}
        }
    },
    "summary": {
        "face_match": 0.5,
        "liveness": 0.5,
        "aml": {
            "status": "pass",
            "matches": [
                {
                    "list": "OFAC_SDN",
                    "entry_id": "string",
                    "score": 0.5,
                    "matched_on": [
                        "name"
                    ]
                }
            ],
            "lists": [
                "OFAC_SDN"
            ]
        },
        "age_over": {
            "threshold": 0,
            "result": true
        }
    },
    "valid_until": "2026-11-07T10:00:00Z",
    "purpose": "string",
    "contract": {
        "reference": "string",
        "sha256": "string"
    },
    "review_deadline_at": "2026-11-07T10:00:00Z",
    "reviewed_by": 0,
    "reviewed_at": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "completed_at": "2026-11-07T10:00:00Z"
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/verifications/{id}/review

Принять решение по проверке ON_HOLD

Рассмотреть можно только проверки ON_HOLD (иначе 409 conflict). Если это последняя проверка заявителя, обновляется и статус заявителя. Отправляет verification.reviewed. comment не сохраняется.

Параметры

  • id string path обязательно
  • Idempotency-Key string header
    Тот же ключ → тот же ответ в течение 24 ч (Idempotent-Replayed: true).

Тело запроса ReviewRequest

  • decision string обязательно
    GREEN RED
  • decision_type string
    Обязательно для RED, запрещено для GREEN. final retry
  • reject_labels RejectLabel[]
    Обязательно для RED, запрещено для GREEN.
  • comment string
    Не сохраняется.
{
    "decision": "GREEN",
    "comment": "manual check ok"
}

Ответы

200 Обновлённая проверка (document.data здесь равно null). Verification
{
    "id": "ver_01j9…",
    "applicant_id": "string",
    "session_id": "string",
    "decision": "GREEN",
    "decision_type": "final",
    "reject_labels": [
        "BAD_QUALITY"
    ],
    "risk_score": 0.5,
    "checks": [
        {
            "name": "document",
            "status": "pass",
            "score": 0.5,
            "labels": [
                "BAD_QUALITY"
            ],
            "details": {
                "lists": [
                    "OFAC_SDN"
                ],
                "matches": [
                    {
                        "list": "OFAC_SDN",
                        "entry_id": "string",
                        "score": 0.5,
                        "matched_on": [
                            "name"
                        ]
                    }
                ],
                "applicant_ids": [
                    "apl_01j9…"
                ],
                "age_over": {
                    "threshold": 18,
                    "result": true
                }
            }
        }
    ],
    "document": {
        "type": "id_card",
        "country": "UZB",
        "data": {
            "first_name": "ANNA MARIA",
            "last_name": "ERIKSSON",
            "middle_name": "string",
            "full_name": "ANNA MARIA ERIKSSON",
            "birth_date": "1994-03-12",
            "place_of_birth": "string",
            "sex": "M",
            "nationality": "UTO",
            "document_type": "passport",
            "document_subtype": "P",
            "issuing_country": "UTO",
            "number": "L898902C3",
            "personal_number": "string",
            "personal_number_type": "JShShIR (PINFL)",
            "personal_number_valid": true,
            "issue_date": "1994-03-12",
            "expiry_date": "1994-03-12",
            "issuing_authority": "string",
            "address": "string",
            "series": "string",
            "division_code": "string",
            "age": 0,
            "is_expired": true,
            "days_to_expiry": 0,
            "names": {
                "mrz": {},
                "viz": {},
                "native": {}
            },
            "fields": {}
        }
    },
    "summary": {
        "face_match": 0.5,
        "liveness": 0.5,
        "aml": {
            "status": "pass",
            "matches": [
                {
                    "list": "OFAC_SDN",
                    "entry_id": "string",
                    "score": 0.5,
                    "matched_on": [
                        "name"
                    ]
                }
            ],
            "lists": [
                "OFAC_SDN"
            ]
        },
        "age_over": {
            "threshold": 0,
            "result": true
        }
    },
    "valid_until": "2026-11-07T10:00:00Z",
    "purpose": "string",
    "contract": {
        "reference": "string",
        "sha256": "string"
    },
    "review_deadline_at": "2026-11-07T10:00:00Z",
    "reviewed_by": 0,
    "reviewed_at": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z",
    "completed_at": "2026-11-07T10:00:00Z"
}
400 validation_failed (ошибки полей в error.fields) или bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — проверка не в статусе ON_HOLD. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/verifications/{id}/media

Сохранённые изображения лица

Изображения лица (AVIF, обычно 2–8 КБ); полное изображение документа никогда не сохраняется. У каждого элемента подписанный URL, действующий 60 с (no-store; просроченная или неподписанная ссылка → 403). При хранении none изображения хранятся 72 ч и только для решений ON_HOLD, иначе items пуст.

Параметры

  • id string path обязательно

Ответы

200 Список медиафайлов. object
{
    "items": [
        {
            "kind": "document_front",
            "content_type": "image/avif",
            "bytes": 0,
            "sha256": "string",
            "url": "https://…",
            "expires_at": "2026-11-07T10:00:00Z",
            "stored_until": "2026-11-07T10:00:00Z"
        }
    ]
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/verifications/{id}/certificate

Справка о проверке с электронной подписью

Справка о проверке с электронной подписью («Tekshiruv dalolatnomasi») по итоговой (GREEN/RED) проверке. Любой может проверить её на публичной странице /verify/{certificate_id} (по реестру, номеру документа или PDF-файлу). Справка никогда не меняется: новое решение выпускает новую версию (version), а старая помечается как заменённая. ?format=pdf возвращает PDF для печати с QR-кодом, ведущим на /verify/{certificate_id}. ON_HOLD → 409 conflict; ключ подписи не настроен → 503 certificate_unavailable.

Параметры

  • id string path обязательно
  • format string query

Ответы

200 Подписанная справка (JSON) или PDF-файл. SignedCertificate
{
    "certificate": {
        "schema": "goxost-kyc/certificate@1",
        "id": "crt_01j9…",
        "version": 0,
        "issued_at": "2026-11-07T10:00:00Z",
        "verify_url": "https://…",
        "issuer": {},
        "requester": {
            "tenant_id": "string",
            "name": "string",
            "project": "string",
            "website": "string"
        },
        "purpose": "string",
        "subject": {},
        "verification": {},
        "checks": [
            {}
        ],
        "images": [
            {
                "kind": "string",
                "sha256": "string"
            }
        ],
        "valid_until": "2026-11-07T10:00:00Z",
        "contract": {
            "reference": "string",
            "sha256": "string"
        },
        "consent": {
            "text_version": "2026-11",
            "given_at": "2026-11-07T10:00:00Z",
            "biometric": true,
            "ip": "string",
            "ip_country": "UZ",
            "device": "iOS 17 · Safari",
            "user_agent": "string"
        }
    },
    "signature": {
        "kid": "string",
        "value": "string"
    },
    "meta": {
        "status": "current",
        "superseded_by": "string"
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
409 conflict — проверка не итоговая (ON_HOLD). Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
503 certificate_unavailable Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/certificates/{certificate_id}

Статус справки

Статус одной из ваших справок (этого аккаунта и окружения). Без персональных данных. valid равно true, только если справка — актуальная версия, решение GREEN и срок valid_until не истёк.

Параметры

  • certificate_id string path обязательно

Ответы

200 Статус справки. CertificateStatus
{
    "certificate_id": "string",
    "version": 0,
    "status": "current",
    "signature_valid": true,
    "valid": true,
    "decision": "GREEN",
    "outcome": "string",
    "issued_at": "2026-11-07T10:00:00Z",
    "valid_until": "2026-11-07T10:00:00Z",
    "expired": true,
    "superseded_by": "string",
    "verify_url": "https://…"
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

AML

Отдельный санкционный скрининг (OFAC SDN, ООН, Великобритания, ЕС; только физические лица).

post /api/v1/aml/screen

Проверить имя по санкционным спискам

Те же правила, что у проверки aml в сценарии: match (RED) — только при совпадении имени и точной даты рождения. Имя и дата никогда не сохраняются и не пишутся в логи. Каждый успешный поиск увеличивает usage.aml_checks; в live — до limit тарифа в месяц, затем 429 plan_limit_reached. Списки не загружены или core недоступен → 503 aml_unavailable (не учитывается).

Параметры

  • Idempotency-Key string header
    Тот же ключ → тот же ответ в течение 24 ч (Idempotent-Replayed: true).

Тело запроса object

  • name string обязательно
    Кириллица или латиница.
  • birth_date string (date) | null
    YYYY-MM-DD, раньше сегодняшней даты. Необязательно, но рекомендуется, чтобы исключить полных тёзок.
{
    "name": "Alisher Karimov",
    "birth_date": "1994-03-12"
}

Ответы

200 Результат проверки. AmlScreenResult
{
    "result": "clear",
    "labels": [
        "SANCTIONS_MATCH"
    ],
    "matches": [
        {
            "list": "OFAC_SDN",
            "entry_id": "string",
            "score": 0.5,
            "matched_on": [
                "name"
            ]
        }
    ],
    "lists": [
        {
            "list": "string",
            "version": "string",
            "entries": 0,
            "updated_at": "2026-11-07T10:00:00Z"
        }
    ]
}
400 validation_failed (ошибки полей в error.fields) или bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
429 plan_limit_reached (месячный лимит боевого режима) или rate_limited. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
503 aml_unavailable Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Сценарии

Настройки проверки. Только чтение; редактируются в панели (каждое изменение — новая версия).

get /api/v1/flows

Список сценариев

Последняя активная версия каждого ключа сценария. У каждого нового аккаунта есть basic-kyc.

Ответы

200 Сценарии. object
{
    "data": [
        {
            "key": "basic-kyc",
            "name": "Basic KYC",
            "version": 0,
            "steps": [
                "consent"
            ],
            "documents": {
                "allowed_countries": [
                    "string"
                ],
                "types": [
                    "passport"
                ],
                "nfc": "off",
                "nfc_fallback": "hold"
            },
            "min_age": 0,
            "checks": {
                "aml": true,
                "duplicate": true,
                "age_only": true
            },
            "retention": {
                "mode": "standard",
                "ttl": "24h"
            },
            "max_attempts": 0
        }
    ]
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/flows/{key}

Получить сценарий

Параметры

  • key string path обязательно

Ответы

200 Последняя активная версия. Flow
{
    "key": "basic-kyc",
    "name": "Basic KYC",
    "version": 0,
    "steps": [
        "consent"
    ],
    "documents": {
        "allowed_countries": [
            "string"
        ],
        "types": [
            "passport"
        ],
        "nfc": "off",
        "nfc_fallback": "hold"
    },
    "min_age": 0,
    "checks": {
        "aml": true,
        "duplicate": true,
        "age_only": true
    },
    "retention": {
        "mode": "standard",
        "ttl": "24h"
    },
    "max_attempts": 0
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Вебхуки

Адреса, принимающие события. Запросы подписываются заголовком KYC-Signature.

get /api/v1/webhooks

Список адресов вебхуков

Ответы

200 Адреса этого окружения. object
{
    "data": [
        {
            "id": "whk_01j9…",
            "url": "https://…",
            "events": [
                "string"
            ],
            "include_document_data": true,
            "is_active": true,
            "status": "ok",
            "created_at": "2026-11-07T10:00:00Z"
        }
    ]
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/webhooks

Создать адрес вебхука

url должен начинаться с https:// и разрешаться в публичный IP (локальные, частные и link-local адреса отклоняются с 400); редиректы не выполняются. Не больше 10 адресов на окружение (422). Секрет подписи secret возвращается только один раз — в этом ответе.

Параметры

  • Idempotency-Key string header
    Тот же ключ → тот же ответ в течение 24 ч (Idempotent-Replayed: true).

Тело запроса WebhookInput + any

  • url string (uri) обязательно
  • events EventType | "*"[] обязательно
  • is_active boolean
  • include_document_data boolean
    По желанию: добавлять извлечённые персональные данные в verification.completed. По умолчанию выключено.
{
    "url": "https://shop.uz/kyc/webhook",
    "events": [
        "verification.completed",
        "verification.on_hold"
    ]
}

Ответы

201 Создано. Webhook + object
{
    "id": "whk_01j9…",
    "url": "https://…",
    "events": [
        "string"
    ],
    "include_document_data": true,
    "is_active": true,
    "status": "ok",
    "created_at": "2026-11-07T10:00:00Z",
    "secret": "whsec_…"
}
400 validation_failed (ошибки полей в error.fields) или bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
422 unprocessable — достигнут лимит адресов (10). Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
patch /api/v1/webhooks/{id}

Изменить адрес вебхука

Частичное обновление. Чтобы приостановить доставку, установите is_active в false.

Параметры

  • id string path обязательно
  • Idempotency-Key string header
    Тот же ключ → тот же ответ в течение 24 ч (Idempotent-Replayed: true).

Тело запроса WebhookInput

  • url string (uri)
  • events EventType | "*"[]
  • is_active boolean
  • include_document_data boolean
    По желанию: добавлять извлечённые персональные данные в verification.completed. По умолчанию выключено.
{
    "is_active": false
}

Ответы

200 Обновлённый адрес. Webhook
{
    "id": "whk_01j9…",
    "url": "https://…",
    "events": [
        "string"
    ],
    "include_document_data": true,
    "is_active": true,
    "status": "ok",
    "created_at": "2026-11-07T10:00:00Z"
}
400 validation_failed (ошибки полей в error.fields) или bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
delete /api/v1/webhooks/{id}

Удалить адрес вебхука

Параметры

  • id string path обязательно
  • Idempotency-Key string header
    Тот же ключ → тот же ответ в течение 24 ч (Idempotent-Replayed: true).

Ответы

204 Удалено.
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/webhooks/{id}/test

Отправить тестовое событие

Ставит в очередь событие webhook.test, даже если адрес приостановлен.

Параметры

  • id string path обязательно
  • Idempotency-Key string header
    Тот же ключ → тот же ответ в течение 24 ч (Idempotent-Replayed: true).

Ответы

202 Поставлено в очередь. object
{
    "delivery_id": "whd_01j9…"
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
get /api/v1/webhooks/{id}/deliveries

Журнал доставок

Последние 100 доставок на адрес, сначала новые.

Параметры

  • id string path обязательно

Ответы

200 Доставки. object
{
    "data": [
        {
            "id": "whd_01j9…",
            "event_id": "evt_01j9…",
            "event": "applicant.created",
            "status": "pending",
            "attempt": 0,
            "status_code": 0,
            "next_retry_at": "2026-11-07T10:00:00Z",
            "delivered_at": "2026-11-07T10:00:00Z",
            "created_at": "2026-11-07T10:00:00Z"
        }
    ]
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
post /api/v1/webhooks/deliveries/{id}/retry

Повторить доставку сейчас

Выполняет доставку немедленно; последующие повторы идут по обычному графику.

Параметры

  • id string path обязательно
    ID доставки из журнала доставок.
  • Idempotency-Key string header
    Тот же ключ → тот же ответ в течение 24 ч (Idempotent-Replayed: true).

Ответы

200 Статус после попытки. object
{
    "status": "pending"
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}
404 not_found — такого ресурса нет в этом аккаунте и окружении. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Использование

Месячные счётчики и лимит тарифа.

get /api/v1/usage

Использование за месяц

Параметры

  • period string query
    YYYY-MM, по умолчанию — текущий месяц (UTC).

Ответы

200 Счётчики. object
{
    "period": "2026-11",
    "plan": "free",
    "limit": 0,
    "live": {
        "verifications": 0,
        "aml_checks": 0,
        "direct_checks": 0
    },
    "sandbox": {
        "verifications": 0,
        "direct_checks": 0
    },
    "core_url": "https://kyc-core.9k.uz/v1"
}
400 validation_failed (ошибки полей в error.fields) или bad_request. Error
{
    "error": {
        "code": "validation_failed",
        "message": "The external id field is required.",
        "fields": {
            "external_id": [
                "The external id field is required."
            ]
        },
        "request_id": "req_01j9…"
    }
}
401 unauthenticated — API-ключ отсутствует или недействителен. Error
{
    "error": {
        "code": "bad_request",
        "message": "string",
        "fields": {},
        "request_id": "req_01j9…"
    }
}

Документы

Публичный каталог поддерживаемых документов, удостоверяющих личность, по странам и уровень их поддержки. Без API-ключа.

get /api/v1/documents/catalog

Каталог поддерживаемых документов

Публичный, только для чтения, без API-ключа (лимит 60/мин на IP). Для каждой страны выдачи (ISO 3166-1 alpha-3; mrz_code — код государства выдачи, напечатанный на документе, например Германия = D) показывает, какие типы документов проверяются и на каком уровне: mrz_full (данные документа полностью считываются и проверяются, возможен автоматический GREEN), mrz_basic (данные считываются, но одно из ключевых полей выводится косвенно — всегда ON_HOLD с DOC_REVIEW_REQUIRED), viz_ocr и manual_review (автоматического GREEN не бывает). Паспорт международного стандарта считывается, даже если выдавшей его страны нет в списке. Формируется из core (contracts/document_catalog.json).

Ответы

200 Каталог. object
{
    "version": "2026-11-08",
    "support_levels": [
        "mrz_full"
    ],
    "types": [
        {
            "type": "passport",
            "formats": [
                "TD3"
            ],
            "support": "mrz_full"
        }
    ],
    "countries": [
        {
            "country": "UZB",
            "mrz_code": "UZB",
            "personal_number": "string",
            "documents": [
                {
                    "type": "passport",
                    "format": "TD3",
                    "support": "mrz_full"
                }
            ],
            "field_profile": {}
        }
    ],
    "field_expectations": [
        "present"
    ],
    "field_profile_defaults": {},
    "field_profiles": {}
}
429 Слишком много запросов.

Вебхуки

post applicant.created

Заявитель создан

Отправляется после POST /applicants.

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • applicant_id string обязательно
    • external_id string обязательно
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string"
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post session.started

Сессия начата

Заявитель дал согласие и начал прохождение сценария. Отправляется один раз за сессию.

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • applicant_id string обязательно
    • external_id string обязательно
    • session_id string обязательно
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string",
        "session_id": "string"
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post verification.submitted

Проверка отправлена

Заявитель прошёл все шаги; начинаются проверки. Отправляется один раз за сессию, после session.started.

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • applicant_id string обязательно
    • external_id string обязательно
    • session_id string обязательно
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string",
        "session_id": "string"
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post verification.completed

Итоговое решение (GREEN/RED)

Полный результат получите через GET /verifications/{verification_id}.

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • applicant_id string обязательно
    • external_id string обязательно
    • verification_id string обязательно
    • decision Decision обязательно
    • decision_type DecisionType обязательно
      Для RED — retry (заявитель может попробовать снова после reset) или final.
    • reject_labels RejectLabel[] обязательно
    • document_data object | null
      Только в verification.completed, если у адреса включено include_document_data: true, — в том же формате, что document.data с ?include=document_data. Каждая попытка доставки — чтение из зашифрованного хранилища с записью в журнал аудита (причина webhook_delivery).
    • document_data_status string
      Передаётся вместе с document_data. not_stored — срок хранения истёк, заявитель удалён или ничего не сохранялось; not_applicable — режим только проверки возраста или документа нет. included not_stored not_applicable
{
    "id": "evt_01j9…",
    "type": "verification.completed",
    "created_at": "2026-11-07T10:05:00Z",
    "env": "live",
    "data": {
        "applicant_id": "apl_01j9…",
        "external_id": "user-8812",
        "verification_id": "ver_01j9…",
        "decision": "GREEN",
        "decision_type": null,
        "reject_labels": []
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post verification.on_hold

Нужна ручная проверка

Решение — ON_HOLD; рассмотрите проверку в панели или через POST /verifications/{id}/review.

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • applicant_id string обязательно
    • external_id string обязательно
    • verification_id string обязательно
    • decision Decision обязательно
    • decision_type DecisionType обязательно
      Для RED — retry (заявитель может попробовать снова после reset) или final.
    • reject_labels RejectLabel[] обязательно
    • document_data object | null
      Только в verification.completed, если у адреса включено include_document_data: true, — в том же формате, что document.data с ?include=document_data. Каждая попытка доставки — чтение из зашифрованного хранилища с записью в журнал аудита (причина webhook_delivery).
    • document_data_status string
      Передаётся вместе с document_data. not_stored — срок хранения истёк, заявитель удалён или ничего не сохранялось; not_applicable — режим только проверки возраста или документа нет. included not_stored not_applicable
{
    "id": "evt_01j9…",
    "type": "verification.completed",
    "created_at": "2026-11-07T10:05:00Z",
    "env": "live",
    "data": {
        "applicant_id": "apl_01j9…",
        "external_id": "user-8812",
        "verification_id": "ver_01j9…",
        "decision": "GREEN",
        "decision_type": null,
        "reject_labels": []
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post verification.reviewed

Проверяющий принял решение

По проверке ON_HOLD принял решение оператор или оно принято через API — либо система отменила проверку после review_deadline_at: тогда decision: RED, decision_type: retry, reject_labels: [REVIEW_EXPIRED] (неподтверждённое предложение по принципу «четырёх глаз» отбрасывается).

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • applicant_id string обязательно
    • external_id string обязательно
    • verification_id string обязательно
    • decision Decision обязательно
    • decision_type DecisionType обязательно
      Для RED — retry (заявитель может попробовать снова после reset) или final.
    • reject_labels RejectLabel[] обязательно
    • document_data object | null
      Только в verification.completed, если у адреса включено include_document_data: true, — в том же формате, что document.data с ?include=document_data. Каждая попытка доставки — чтение из зашифрованного хранилища с записью в журнал аудита (причина webhook_delivery).
    • document_data_status string
      Передаётся вместе с document_data. not_stored — срок хранения истёк, заявитель удалён или ничего не сохранялось; not_applicable — режим только проверки возраста или документа нет. included not_stored not_applicable
{
    "id": "evt_01j9…",
    "type": "verification.completed",
    "created_at": "2026-11-07T10:05:00Z",
    "env": "live",
    "data": {
        "applicant_id": "apl_01j9…",
        "external_id": "user-8812",
        "verification_id": "ver_01j9…",
        "decision": "GREEN",
        "decision_type": null,
        "reject_labels": []
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post verification.review_reminder

Напоминание о сроке ручной проверки

Отправляется по проверке ON_HOLD сразу после перевода в ON_HOLD, когда остаётся 2 дня и когда остаётся 24 часа (каждый этап не более одного раза; проверка раз в час). После review_deadline_at проверка отменяется (verification.reviewed с REVIEW_EXPIRED).

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • verification_id string обязательно
    • applicant_id string обязательно
    • review_deadline_at string (date-time) обязательно
    • hours_left integer обязательно
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "verification_id": "string",
        "applicant_id": "string",
        "review_deadline_at": "2026-11-07T10:00:00Z",
        "hours_left": 0
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post certificate.issued

Справка выпущена

Выпущена подписанная справка (или её новая версия после повторного рассмотрения) — примерно через 5 минут после итогового решения. Скачайте её по certificate_url / pdf_url со своим API-ключом. При include_document_data: true событие также содержит certificate (подписанный документ), pdf_base64 и certificate_status (included · not_stored).

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • certificate_id string обязательно
    • version integer обязательно
    • verification_id string обязательно
    • applicant_id string обязательно
    • external_id string | null
    • decision string обязательно
      GREEN RED
    • issued_at string (date-time) обязательно
    • valid_until string (date-time) | null
    • supersedes string | null
    • verify_url string (uri) обязательно
    • certificate_url string (uri) обязательно
    • pdf_url string (uri) обязательно
    • certificate SignedCertificate
    • pdf_base64 string | null
    • certificate_status string
      included not_stored
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "certificate_id": "string",
        "version": 0,
        "verification_id": "string",
        "applicant_id": "string",
        "external_id": "string",
        "decision": "GREEN",
        "issued_at": "2026-11-07T10:00:00Z",
        "valid_until": "2026-11-07T10:00:00Z",
        "supersedes": "string",
        "verify_url": "https://…",
        "certificate_url": "https://…",
        "pdf_url": "https://…",
        "certificate": {
            "certificate": {
                "schema": "goxost-kyc/certificate@1",
                "id": "crt_01j9…",
                "version": 0,
                "issued_at": "2026-11-07T10:00:00Z",
                "verify_url": "https://…",
                "issuer": {},
                "requester": {
                    "tenant_id": "string",
                    "name": "string",
                    "project": "string",
                    "website": "string"
                },
                "purpose": "string",
                "subject": {},
                "verification": {},
                "checks": [
                    {}
                ],
                "images": [
                    {
                        "kind": "string",
                        "sha256": "string"
                    }
                ],
                "valid_until": "2026-11-07T10:00:00Z",
                "contract": {
                    "reference": "string",
                    "sha256": "string"
                },
                "consent": {
                    "text_version": "2026-11",
                    "given_at": "2026-11-07T10:00:00Z",
                    "biometric": true,
                    "ip": "string",
                    "ip_country": "UZ",
                    "device": "iOS 17 · Safari",
                    "user_agent": "string"
                }
            },
            "signature": {
                "kid": "string",
                "value": "string"
            },
            "meta": {
                "status": "current",
                "superseded_by": "string"
            }
        },
        "pdf_base64": "string",
        "certificate_status": "included"
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post applicant.reverification_due

Требуется повторная проверка

Проверка GREEN действует 2 года (valid_until). Отправляется один раз, когда остаётся 30 дней (stage: due_soon), и один раз по истечении срока (stage: expired); проверяется ежедневно и только для последней проверки заявителя.

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • applicant_id string обязательно
    • verification_id string обязательно
    • valid_until string (date-time) обязательно
    • stage string обязательно
      due_soon expired
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "verification_id": "string",
        "valid_until": "2026-11-07T10:00:00Z",
        "stage": "due_soon"
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post applicant.reset

Заявитель сброшен

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • applicant_id string обязательно
    • external_id string обязательно
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string"
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post applicant.deleted

Заявитель удалён

data.external_id — исходное значение (до анонимизации).

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • applicant_id string обязательно
    • external_id string обязательно
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string"
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post aml.match

Совпадение при постоянном мониторинге

Зарезервировано для постоянного AML-мониторинга (пока не отправляется).

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • applicant_id string обязательно
    • external_id string обязательно
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "applicant_id": "string",
        "external_id": "string"
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.
post webhook.test

Тестовое событие

Отправляется через POST /webhooks/{id}/test.

Параметры

  • KYC-Signature string header обязательно
    t=<unix seconds>,v1=<hex>, где v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Проверяйте HMAC по сырому телу запроса и отклоняйте t, отличающийся от текущего времени больше чем на ±5 минут. Ответы не 2xx повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; если все попытки неудачны, адрес помечается как failing до следующей успешной доставки.

Тело запроса Event + object

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    • webhook_id string обязательно
{
    "id": "evt_01j9…",
    "type": "applicant.created",
    "created_at": "2026-11-07T10:00:00Z",
    "env": "sandbox",
    "data": {
        "webhook_id": "string"
    }
}

Ответы

2XX Подтвердите получение любым ответом 2xx.

Модели

Error

object
  • error object обязательно
    • code ErrorCode обязательно
      400 bad_request, validation_failed · 401 unauthenticated · 403 forbidden · 404 not_found · 409 conflict, idempotency_conflict · 413 file_too_large (тело запроса больше лимита сервера) · 422 unprocessable · 429 rate_limited, plan_limit_reached · 5xx internal_error, aml_unavailable.
    • message string обязательно
    • fields object
      Поле → список сообщений (только для ошибок валидации).
    • request_id string обязательно

ErrorCode

string

400 bad_request, validation_failed · 401 unauthenticated · 403 forbidden · 404 not_found · 409 conflict, idempotency_conflict · 413 file_too_large (тело запроса больше лимита сервера) · 422 unprocessable · 429 rate_limited, plan_limit_reached · 5xx internal_error, aml_unavailable.

bad_request validation_failed unauthenticated forbidden not_found conflict idempotency_conflict file_too_large unprocessable rate_limited plan_limit_reached internal_error aml_unavailable

Locale

string
uz ru en

Environment

string
sandbox live

ApplicantStatus

string

init — новый, после reset или после RED с retry; pending зарезервирован и сейчас не устанавливается.

init pending on_hold completed

Decision

string
GREEN RED ON_HOLD

DecisionType

string | null

Для RED — retry (заявитель может попробовать снова после reset) или final.

final retry

RejectLabel

string

Код причины (см. таблицу причин отказа). DOC_RECAPTURE (RED retry) — только если её включил оператор. AGE_UNKNOWN (review → ON_HOLD) — только в сценариях с проверкой возраста (checks.age_only). PERSONAL_NUMBER_INVALID и DOC_REVIEW_REQUIRED — метки ручной проверки (→ ON_HOLD). Считывание данных документа: MRZ_NOT_READABLE (retry) — данные не удалось надёжно считать, попросите новое фото; MRZ_INVALID — переданные данные документа или даты неверны; MRZ_LOW_CONFIDENCE (→ ON_HOLD) — данные считаны с низкой уверенностью; DOC_DATA_MISMATCH — данные документа не согласуются между собой. Электронная проверка документа (сценарий documents.nfc, только мобильный SDK): CHIP_HASH_MISMATCH, CHIP_SIGNATURE_INVALID, CHIP_MRZ_MISMATCH — окончательный RED; CHIP_CHAIN_UNVERIFIED, CHIP_CLONE_SUSPECTED, CHIP_NOT_READ — метки ручной проверки (→ ON_HOLD). Проверка подлинности документа (doc_fraud): DOC_SCREEN_RECAPTURE, DOC_PRINTED_COPY, DOC_PHOTO_TAMPERED, DOC_TEMPLATE_MISMATCH — изображение документа не прошло проверку подлинности; это метки ручной проверки (→ ON_HOLD). REVIEW_EXPIRED (RED retry) выставляет только система, если проверка ON_HOLD не была рассмотрена до review_deadline_at; выбрать её при ручной проверке нельзя.

BAD_QUALITY DOC_NOT_SUPPORTED MRZ_NOT_READABLE MRZ_INVALID MRZ_LOW_CONFIDENCE DOC_DATA_MISMATCH DOC_EXPIRED DOC_RECAPTURE DOC_FORGED UNDERAGE FACE_NOT_FOUND FACE_MISMATCH FACE_MATCH_UNCERTAIN LIVENESS_FAILED LIVENESS_SPOOF LIVENESS_UNCERTAIN SANCTIONS_MATCH SANCTIONS_POSSIBLE CHECK_UNAVAILABLE PEP_MATCH DUPLICATE MAX_ATTEMPTS DOC_FACE_UNBOUND AML_NO_NAME AGE_UNKNOWN PERSONAL_NUMBER_INVALID DOC_REVIEW_REQUIRED CHIP_HASH_MISMATCH CHIP_SIGNATURE_INVALID CHIP_CHAIN_UNVERIFIED CHIP_MRZ_MISMATCH CHIP_CLONE_SUSPECTED CHIP_NOT_READ DOC_SCREEN_RECAPTURE DOC_PRINTED_COPY DOC_PHOTO_TAMPERED DOC_TEMPLATE_MISMATCH REVIEW_EXPIRED

DocumentType

string

residence_permit и visa добавлены 2026-11-08; сценарий, в котором перечислены только прежние типы (id_card, passport, ru_internal_passport) и есть id_card, принимает также residence_permit (раньше он определялся как id_card). driving_licence зарезервирован (пока не считывается автоматически).

passport id_card residence_permit ru_internal_passport visa driving_licence

SupportLevel

string
mrz_full mrz_basic viz_ocr manual_review

CertificateStatus

object
  • certificate_id string | null обязательно
  • version integer | null обязательно
  • status string обязательно
    current superseded revoked invalid_signature unknown
  • signature_valid boolean обязательно
  • valid boolean обязательно
    актуальная версия + GREEN + срок не истёк
  • decision string | null обязательно
    GREEN RED
  • outcome string | null
  • issued_at string (date-time) | null обязательно
  • valid_until string (date-time) | null обязательно
  • expired boolean обязательно
  • superseded_by string | null обязательно
  • verify_url string (uri) | null обязательно

EventType

string
applicant.created session.started verification.submitted verification.completed verification.on_hold verification.reviewed verification.review_reminder applicant.reverification_due certificate.issued applicant.reset applicant.deleted aml.match webhook.test

ApplicantCreate

object
  • external_id string обязательно
    ID пользователя у вас; печатные ASCII-символы, уникален в пределах окружения.
  • flow string
  • locale Locale
  • purpose string | null
    Цель проверки по умолчанию для сессий этого заявителя.
  • metadata object
    Строки ключ/значение без персональных данных, ≤ 2 КБ в виде JSON.
  • email —
    Пока не принимается: непустое значение → 400 validation_failed (fields.email). Не сохраняется и не возвращается (зашифрованное хранение контактов появится позже).
  • phone —
    Пока не принимается: непустое значение → 400 validation_failed (fields.phone). Не сохраняется и не возвращается.

Applicant

object
  • id string обязательно
  • external_id string обязательно
  • flow string обязательно
  • locale Locale обязательно
  • status ApplicantStatus обязательно
    init — новый, после reset или после RED с retry; pending зарезервирован и сейчас не устанавливается.
  • decision Decision | null обязательно
  • risk_score number | null обязательно
  • last_verification_id string | null обязательно
  • metadata object обязательно
  • purpose string | null
  • valid_until string (date-time) | null
    Срок действия последней проверки (только GREEN: дата решения + 2 года).
  • created_at string (date-time) обязательно
  • updated_at string (date-time) обязательно
  • identity object | null
    Только с ?include=identity. null, если у заявителя нет проверки GREEN.
    • verification_id string обязательно
    • verified_at string (date-time) обязательно
    • document object | null обязательно
      • type string обязательно
      • country string | null обязательно
      • data DocumentData | null обязательно

Session

object
  • id string обязательно
  • applicant_id string обязательно
  • status string обязательно
    created started submitted processed expired abandoned
  • locale Locale обязательно
  • flow_version integer обязательно
  • steps_done string[] обязательно
  • expires_at string (date-time) обязательно
  • started_at string (date-time) | null обязательно
  • submitted_at string (date-time) | null обязательно
  • created_at string (date-time) обязательно
  • purpose string | null
  • contract ContractBinding | null

ContractBinding

object

Привязывает проверку к вашему договору с клиентом. Сохраняется только хеш; он включается в подписанную справку.

  • reference string | null
    Номер вашего договора.
  • sha256 string обязательно
    SHA-256 файла договора (hex; возвращается в нижнем регистре).

SignedCertificate

object
  • certificate object обязательно
    Подписанные поля (полный пример — в API.md §3.3). Ключи без значения опускаются, кроме consent.
    • schema "goxost-kyc/certificate@1" обязательно
    • id string обязательно
    • version integer обязательно
    • issued_at string (date-time) обязательно
    • verify_url string (uri) обязательно
    • issuer object обязательно
    • requester object обязательно
      • tenant_id string обязательно
      • name string обязательно
        Юридическое название из профиля бизнеса, иначе название компании.
      • project string
      • website string
    • purpose string
    • subject object обязательно
      applicant_id, external_id, full_name, birth_date и document {type, country, number_masked}.
    • verification object обязательно
    • checks object[] обязательно
    • images object[] обязательно
      • kind string
      • sha256 string
    • valid_until string (date-time)
    • contract ContractBinding
      Привязывает проверку к вашему договору с клиентом. Сохраняется только хеш; он включается в подписанную справку.
    • consent object | null обязательно
      Подтверждение согласия (в том числе в тестовом режиме). Присутствует всегда; null, если согласие не было зафиксировано (старые проверки). IP-адрес и user agent есть только в справке — никогда в GET /verifications/{id}, вебхуках или на публичной странице /verify. Схема остаётся goxost-kyc/certificate@1.
      • text_version string обязательно
      • given_at string (date-time) обязательно
      • biometric boolean обязательно
        Согласие на обработку биометрических данных (лица).
      • ip string | null обязательно
        IPv4- или IPv6-адрес, с которого дано согласие.
      • ip_country string | null обязательно
      • device string | null обязательно
        Краткое описание user agent.
      • user_agent string | null обязательно
  • signature object обязательно
    • kid string обязательно
    • value string обязательно
      Электронная подпись certificate. Её проверяет только GOXOST KYC.
  • meta object обязательно
    Не подписывается.
    • status string
      current superseded
    • superseded_by string | null

Check

object
  • name string обязательно
  • status string обязательно
    pass warn fail error
  • score number | null обязательно
  • labels RejectLabel[] обязательно
  • details object
    Есть только у некоторых проверок (aml → lists и при совпадении matches; duplicate → applicant_ids, age → age_over). Без персональных данных.
    • lists string[]
      Санкционные списки, по которым фактически прошла эта проверка aml. Необязательный список (ЕС) отсутствует, если он не загружен или устарел.
    • matches AmlMatch[]
    • applicant_ids string[]
      Другие заявители вашего аккаунта с тем же номером документа (сначала старые). В тестовом режиме не возвращается.
    • age_over object
      Сценарии только с проверкой возраста (checks.age_only). Сама дата рождения никогда не возвращается.
      • threshold integer обязательно
        min_age сценария.
      • result boolean | null обязательно
        true — не младше threshold лет, false — младше (UNDERAGE), null — дата рождения неизвестна (AGE_UNKNOWN).

Verification

object
  • id string обязательно
  • applicant_id string обязательно
  • session_id string обязательно
  • decision Decision обязательно
  • decision_type DecisionType обязательно
    Для RED — retry (заявитель может попробовать снова после reset) или final.
  • reject_labels RejectLabel[] обязательно
  • risk_score number | null обязательно
  • checks Check[] обязательно
  • document object | null обязательно
    • type string обязательно
      DocumentType или unknown.
    • country string | null обязательно
      ISO 3166-1 alpha-3.
    • data DocumentData | null обязательно
      Расшифрованные поля документа (персональные данные). Когда они доступны — см. описание операции. В сценариях только с проверкой возраста всегда null.
  • summary object
    Сводка баллов проверок без персональных данных. Ключ равен null, если эта проверка не выполнялась.
    • face_match number | null
    • liveness number | null
    • aml object | null
      • status string
        pass warn fail error
      • matches AmlMatch[]
      • lists string[]
    • age_over object | null
      • threshold integer
      • result boolean | null
  • valid_until string (date-time) | null
    Только GREEN: время решения + 2 года. Пройдите повторную проверку до этого срока (applicant.reverification_due).
  • purpose string | null
  • contract ContractBinding | null
  • review_deadline_at string (date-time) | null
    Только ON_HOLD: рассмотрите до этого времени (ON_HOLD + 7 дней), иначе проверка отменяется (RED REVIEW_EXPIRED). null для автоматических решений.
  • reviewed_by integer | null обязательно
    ID пользователя панели, принявшего решение; null для автоматических решений, решений через API и системной отмены.
  • reviewed_at string (date-time) | null обязательно
  • created_at string (date-time) обязательно
  • completed_at string (date-time) | null обязательно
    null, пока статус ON_HOLD.

VaultReadReason

string

Причина чтения из зашифрованного хранилища для журнала аудита (по умолчанию api_request). Неизвестное значение → 400 validation_failed.

panel_view manual_review customer_request compliance_audit legal_request api_request

DocumentData

object

Поля, считанные с документа (персональные данные). Ключи со временем только добавляются и никогда не удаляются; несчитанное поле равно null. В старых записях хранилища новые ключи равны null. Примеры значений взяты из синтетического образца документа «Utopia».

  • first_name string | null
  • last_name string | null
  • middle_name string | null
    Отчество (во внутреннем паспорте РФ также сохраняется patronymic).
  • full_name string | null
    first_name middle_name last_name.
  • birth_date string (date) | null
  • place_of_birth string | null
  • sex string | null
    M F X
  • nationality string | null
  • document_type string | null
  • document_subtype string | null
    Код типа документа, напечатанный на документе.
  • issuing_country string | null
  • number string | null
  • personal_number string | null
  • personal_number_type string | null
  • personal_number_valid boolean | null
    Результат проверки по национальному алгоритму контрольной суммы; null, если валидатора нет.
  • issue_date string (date) | null
  • expiry_date string (date) | null
  • issuing_authority string | null
  • address string | null
    Пока не считывается ни с одного документа; см. fields.address.status.
  • series string
    Только внутренний паспорт РФ.
  • division_code string
    Только внутренний паспорт РФ.
  • age integer | null
    Вычисляется в момент чтения (текущая дата по UTC).
  • is_expired boolean | null
  • days_to_expiry integer | null
    Отрицательное, если срок истёк.
  • names object | null
    • mrz object | null
      Имена латиницей, считанные с документа.
    • viz object | null
      Имена из резервного считывания, если основное считывание не удалось.
    • native object | null
      Национальное письмо (внутренний паспорт РФ — кириллица).
  • fields object | null
    По каждому полю. Все считанные поля, а также middle_name, issue_date, place_of_birth, issuing_authority, address, native_name и personal_number, даже если их значение null (со status). Статус никогда не влияет на решение.

ReviewRequest

object
  • decision string обязательно
    GREEN RED
  • decision_type string
    Обязательно для RED, запрещено для GREEN. final retry
  • reject_labels RejectLabel[]
    Обязательно для RED, запрещено для GREEN.
  • comment string
    Не сохраняется.

MediaItem

object
  • kind string обязательно
    Что изображено на снимке. document_front document_back document_face selfie_face liveness_frame
  • content_type string обязательно
  • bytes integer обязательно
  • sha256 string | null
    SHA-256 байтов изображения (null для объектов, сохранённых до 2026-11-08).
  • url string (uri) обязательно
  • expires_at string (date-time) обязательно
    В это время истекает срок действия подписанного URL.
  • stored_until string (date-time) | null
    В это время само изображение удаляется (через 7 дней после обработки).

AmlMatch

object
  • list string обязательно
    OFAC_SDN UN UK EU
  • entry_id string обязательно
    По этому ID запись можно открыть на сайте источника списка (имя из списка не возвращается).
  • score number обязательно
  • matched_on string[] обязательно

AmlScreenResult

object
  • result string обязательно
    possible требует ручной проверки; match = имя + точная дата рождения. clear possible match
  • labels string[] обязательно
  • matches AmlMatch[] обязательно
  • lists object[] обязательно
    Версии списков, использованных в этом поиске (необязательный список, например ЕС, отсутствует, если он не загружен или устарел).
    • list string обязательно
    • version string обязательно
      Начальная часть sha256 исходного файла.
    • entries integer обязательно
    • updated_at string (date-time) обязательно

Flow

object
  • key string обязательно
  • name string обязательно
  • version integer обязательно
  • steps string[] обязательно
  • documents object обязательно
    • allowed_countries string[]
      Коды государства выдачи, как они напечатаны на документе (1–3 буквы, например UZB, Германия = D), или ["*"] = любое.
    • types DocumentType[]
    • nfc string
      Электронная проверка документа в мобильном SDK (проверка chip). В веб-сценарии недоступна. off optional required
    • nfc_fallback string
      required, но электронная проверка документа не выполнялась (например, веб-сценарий): hold → CHIP_NOT_READ (ON_HOLD); block → отправка (submit) возвращает 409 nfc_required. hold block
  • min_age integer обязательно
  • checks object обязательно
    • aml boolean
    • duplicate boolean
    • age_only boolean
      Подтверждает только, что заявителю не меньше min_age лет (проверка age); данные документа не возвращаются и не сохраняются. Никогда не сочетается с aml или duplicate.
  • retention object обязательно
    • mode string
      standard (по умолчанию для новых аккаунтов) — изображения 7 дней + текстовые данные на срок ttl; none — текст не хранится, изображения — только для ON_HOLD (7 дней). compact — устаревшее значение, обрабатывается как standard. standard none compact
    • ttl string | null
      Срок хранения текстовых данных для standard/compact (1y или 5y, по умолчанию 5y; 24h/30d — только устаревшие значения), null для none. 24h 30d 1y 5y
  • max_attempts integer обязательно
    Только для информации — пока не применяется (MAX_ATTEMPTS никогда не отправляется).

WebhookInput

object
  • url string (uri)
  • events EventType | "*"[]
  • is_active boolean
  • include_document_data boolean
    По желанию: добавлять извлечённые персональные данные в verification.completed. По умолчанию выключено.

Webhook

object
  • id string обязательно
  • url string (uri) обязательно
  • events string[] обязательно
  • include_document_data boolean обязательно
  • is_active boolean обязательно
  • status string обязательно
    failing — последняя доставка не удалась после всех повторов. ok failing
  • created_at string (date-time) обязательно

DeliveryStatus

string
pending delivered failed

WebhookDelivery

object
  • id string обязательно
  • event_id string обязательно
  • event EventType обязательно
  • status DeliveryStatus обязательно
  • attempt integer обязательно
  • status_code integer | null обязательно
    HTTP-статус, который вернул ваш адрес.
  • next_retry_at string (date-time) | null обязательно
  • delivered_at string (date-time) | null обязательно
  • created_at string (date-time) обязательно

Event

object

Конверт вебхука. Не содержит персональных данных; подробности получите через API.

  • id string обязательно
  • type EventType обязательно
  • created_at string (date-time) обязательно
  • env Environment обязательно
  • data object обязательно
    Зависит от type: - applicant.created, applicant.reset, applicant.deleted — {applicant_id, external_id} (для deleted — исходный external_id; отправляется до уничтожения сохранённых данных). - session.started, verification.submitted — {applicant_id, external_id, session_id}. - verification.completed, verification.on_hold, verification.reviewed — {applicant_id, external_id, verification_id, decision, decision_type, reject_labels}. - webhook.test — {webhook_id}. Доставка: первая попытка + 6 повторов (1 мин, 5 мин, 30 мин, 2 ч, 6 ч, 24 ч), таймаут 10 с.