Документы и медиа
Tenant API предоставляет эндпоинты для получения информации о поддерживаемых типах документов и доступа к загруженным медиафайлам (фотографии документов, селфи). Загрузка файлов осуществляется автоматически в процессе прохождения верификации на стороне OneKYC.
Поддерживаемые типы документов
Возвращает перечень типов документов, поддерживаемых платформой, с указанием стран и допустимых форматов. Требуемый scope: documents:read.
ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
Supported documents list
application/json- response
data?unknownsuccess?booleancurl -X GET 'https://api.onekyc.io/tenant/v1/kyc/documents/supported' \ -H 'X-Timestamp: string'{ "data": null, "success": true}Получение медиафайла
Возвращает подписанную ссылку для скачивания медиафайла по его идентификатору. Требуемый scope: media:read.
ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
media_id*stringMedia UUID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
Presigned URL
application/json- response
data?unknownsuccess?booleancurl -X GET 'https://api.onekyc.io/tenant/v1/kyc/media/string' \ -H 'X-Timestamp: string'{ "data": null, "success": true}Примечание. Идентификаторы медиафайлов содержатся в данных аппликанта и в списке документов аппликанта. Подписанная ссылка на медиафайл имеет ограниченный срок действия.
Как скачать файлы после получения вебхука
При получении вебхука (например, session.completed или verification.approved) в payload присутствуют:
applicant_id— идентификатор аппликантаmedia— объект со storage keys (информационные, не являются идентификаторами для API)
Рекомендуемый порядок:
-
Получить данные аппликанта —
GET /v1/kyc/applicants/{applicant_id}. Ответ содержит готовые подписанные ссылки:document_photo_url,document_front_url,document_back_url— фотографии документаportrait_photo_url— портрет из документаselfie_photo_url— селфиavatar_photo_url— аватарphoto_url_expires_at— срок действия ссылок
-
Или получить список документов —
GET /v1/kyc/applicants/{applicant_id}/documents. Если у вас есть только ваш внешний идентификатор, используйтеGET /v1/kyc/applicants/external/{external_id}/documents. Ответ содержитidкаждого документа (UUID), который можно использовать дляGET /v1/kyc/media/{media_id}. -
Скачать файл по подписанной ссылке (HTTP GET, без аутентификации). Ссылка действительна ограниченное время.
Важно. Поле
mediaв вебхуке содержит внутренние storage keys, а не идентификаторы для API. Для скачивания используйте подписанные ссылки из ответаGET /v1/kyc/applicants/{applicant_id}.
Документы аппликанта
Возвращает список документов, загруженных конкретным аппликантом в рамках верификации. Требуемый scope: documents:read.
ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
applicant_id*stringApplicant UUID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
Documents list
application/json- response
data?array<>pagination?success?booleancurl -X GET 'https://api.onekyc.io/tenant/v1/kyc/applicants/string/documents' \ -H 'X-Timestamp: string'{ "pagination": { "has_more": true, "limit": 0, "next_cursor": "string", "offset": 0, "total": 0 }, "success": true, "data": [ { "attempt_number": 0, "collection": { "doc_liveness": { "is_real": true, "portrait_replace": 0, "printed_copy": 0, "result_code": "string", "score": 0, "screen_replay": 0, "status": "string", "status_error": "string", "thresholds": { "portrait_replace": 0, "printed_copy": 0, "screen_replay": 0 } }, "doc_liveness_sides": { "property1": { "is_real": true, "portrait_replace": 0, "printed_copy": 0, "result_code": "string", "score": 0, "screen_replay": 0, "status": "string", "status_error": "string", "thresholds": { "portrait_replace": 0, "printed_copy": 0, "screen_replay": 0 } }, "property2": { "is_real": true, "portrait_replace": 0, "printed_copy": 0, "result_code": "string", "score": 0, "screen_replay": 0, "status": "string", "status_error": "string", "thresholds": { "portrait_replace": 0, "printed_copy": 0, "screen_replay": 0 } } }, "document_metadata": { "back_file_id": "string", "front_file_id": "string", "portrait_file_id": "string", "primary_file_id": "string" }, "document_order": 0, "logical_document_id": "string", "ocr": { "additional": { "property1": "string", "property2": "string" }, "address": "string", "barcode": { "property1": "string", "property2": "string" }, "booklet_number": "string", "date_of_birth": "string", "document_class": "string", "document_name": "string", "document_number": "string", "document_series": "string", "document_type": "string", "expiry_date": "string", "field_issues": { "property1": "string", "property2": "string" }, "first_name": "string", "full_name": "string", "full_name_latin": "string", "gender": "string", "issue_date": "string", "issuing_authority": "string", "issuing_authority_name": "string", "issuing_country": "string", "issuing_place": "string", "issuing_state_code": "string", "last_name": "string", "localized": { "property1": { "property1": "string", "property2": "string" }, "property2": { "property1": "string", "property2": "string" } }, "middle_name": "string", "mrz_code": "string", "mrz_data": { "property1": "string", "property2": "string" }, "mrz_type": "string", "nationality": "string", "nationality_name": "string", "native_full_name": "string", "personal_number": "string", "place_of_birth": "string", "portrait": "string", "portrait_position": { "x1": 0, "x2": 0, "y1": 0, "y2": 0 }, "position": { "x1": 0, "x2": 0, "y1": 0, "y2": 0 }, "profession": "string", "reconciliation": { "canonical_name": { "confidence": 0, "full_name": "string", "given_names": "string", "language": "string", "script": "string", "source": "mrz", "surname": "string" }, "confidence": 0, "conflicts": [ { "code": "name_mismatch", "field": "string", "left_source": "mrz", "right_source": "mrz", "severity": "string" } ], "decision": "accept", "evidence_sufficient": true, "fixable_by_recapture": true, "model": "string", "mrz": { "decision_source": "string", "independent_available": true, "independent_valid": true, "parsed": { "checks": { "property1": { "expected": "string", "observed": "string", "valid": true }, "property2": { "expected": "string", "observed": "string", "valid": true } }, "date_of_birth": "string", "document_number": "string", "expiry_date": "string", "given_names": "string", "layout": "TD1", "nationality": "string", "raw_lines": [ "string" ], "sex": "string", "surname": "string", "valid": true, "validation_complete": true }, "provider_state": "valid", "provider_validation": "string", "shadow_decision_applied": true, "shadow_state": "valid" }, "names": [ { "confidence": 0, "full_name": "string", "given_names": "string", "language": "string", "script": "string", "source": "mrz", "surname": "string" } ], "recommended_action": "continue" }, "tax_number": "string" }, "review_decision": { "automatic_status": "string", "decided_at": "string", "decision": "string", "source": "string" }, "revision": 0, "status": "string" }, "created_at": "string", "extracted_data": { "date_of_birth": "string", "date_of_issue": "string", "document_number": "string", "document_type": "string", "expiry_date": "string", "extended_data": { "property1": "string", "property2": "string" }, "first_name": "string", "full_name": "string", "full_name_latin": "string", "full_name_native": "string", "full_name_original": "string", "gender": "string", "issuing_country": "string", "last_name": "string", "middle_name": "string", "mrz": "string", "nationality": "string", "ocr": { "additional": { "property1": "string", "property2": "string" }, "address": "string", "barcode": { "property1": "string", "property2": "string" }, "booklet_number": "string", "date_of_birth": "string", "document_class": "string", "document_name": "string", "document_number": "string", "document_series": "string", "document_type": "string", "expiry_date": "string", "field_issues": { "property1": "string", "property2": "string" }, "first_name": "string", "full_name": "string", "full_name_latin": "string", "gender": "string", "issue_date": "string", "issuing_authority": "string", "issuing_authority_name": "string", "issuing_country": "string", "issuing_place": "string", "issuing_state_code": "string", "last_name": "string", "localized": { "property1": { "property1": "string", "property2": "string" }, "property2": { "property1": "string", "property2": "string" } }, "middle_name": "string", "mrz_code": "string", "mrz_data": { "property1": "string", "property2": "string" }, "mrz_type": "string", "nationality": "string", "nationality_name": "string", "native_full_name": "string", "personal_number": "string", "place_of_birth": "string", "portrait": "string", "portrait_position": { "x1": 0, "x2": 0, "y1": 0, "y2": 0 }, "position": { "x1": 0, "x2": 0, "y1": 0, "y2": 0 }, "profession": "string", "reconciliation": { "canonical_name": { "confidence": 0, "full_name": "string", "given_names": "string", "language": "string", "script": "string", "source": "mrz", "surname": "string" }, "confidence": 0, "conflicts": [ { "code": "name_mismatch", "field": "string", "left_source": "mrz", "right_source": "mrz", "severity": "string" } ], "decision": "accept", "evidence_sufficient": true, "fixable_by_recapture": true, "model": "string", "mrz": { "decision_source": "string", "independent_available": true, "independent_valid": true, "parsed": { "checks": { "property1": { "expected": "string", "observed": "string", "valid": true }, "property2": { "expected": "string", "observed": "string", "valid": true } }, "date_of_birth": "string", "document_number": "string", "expiry_date": "string", "given_names": "string", "layout": "TD1", "nationality": "string", "raw_lines": [ "string" ], "sex": "string", "surname": "string", "valid": true, "validation_complete": true }, "provider_state": "valid", "provider_validation": "string", "shadow_decision_applied": true, "shadow_state": "valid" }, "names": [ { "confidence": 0, "full_name": "string", "given_names": "string", "language": "string", "script": "string", "source": "mrz", "surname": "string" } ], "recommended_action": "continue" }, "tax_number": "string" }, "place_of_birth": "string" }, "id": "string", "is_current": true, "issuing_country": "string", "pages": [ { "download_url": "string", "download_url_expires_at": "string", "image_id": "string", "side": "string" } ], "reason_codes": [ "string" ], "session_id": "string", "side": "string", "status": "string", "step_id": "string", "type": "string", "verification": { "checks": [ { "is_authentic": true, "liveness_score": 0, "portrait_replace_score": 0, "printed_copy_score": 0, "rejection_reasons": [ "string" ], "screen_replay_score": 0, "similarity_score": 0, "status": "string", "type": "string" } ], "status": "string" } } ]}Документы аппликанта по external_id
Возвращает тот же список документов по external_id, который вы передали при создании ссылки верификации. Требуемый scope: documents:read.
ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
external_id*stringExternal user ID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
Documents list
application/json- response
data?array<>pagination?success?booleancurl -X GET 'https://api.onekyc.io/tenant/v1/kyc/applicants/external/string/documents' \ -H 'X-Timestamp: string'{ "pagination": { "has_more": true, "limit": 0, "next_cursor": "string", "offset": 0, "total": 0 }, "success": true, "data": [ { "attempt_number": 0, "collection": { "doc_liveness": { "is_real": true, "portrait_replace": 0, "printed_copy": 0, "result_code": "string", "score": 0, "screen_replay": 0, "status": "string", "status_error": "string", "thresholds": { "portrait_replace": 0, "printed_copy": 0, "screen_replay": 0 } }, "doc_liveness_sides": { "property1": { "is_real": true, "portrait_replace": 0, "printed_copy": 0, "result_code": "string", "score": 0, "screen_replay": 0, "status": "string", "status_error": "string", "thresholds": { "portrait_replace": 0, "printed_copy": 0, "screen_replay": 0 } }, "property2": { "is_real": true, "portrait_replace": 0, "printed_copy": 0, "result_code": "string", "score": 0, "screen_replay": 0, "status": "string", "status_error": "string", "thresholds": { "portrait_replace": 0, "printed_copy": 0, "screen_replay": 0 } } }, "document_metadata": { "back_file_id": "string", "front_file_id": "string", "portrait_file_id": "string", "primary_file_id": "string" }, "document_order": 0, "logical_document_id": "string", "ocr": { "additional": { "property1": "string", "property2": "string" }, "address": "string", "barcode": { "property1": "string", "property2": "string" }, "booklet_number": "string", "date_of_birth": "string", "document_class": "string", "document_name": "string", "document_number": "string", "document_series": "string", "document_type": "string", "expiry_date": "string", "field_issues": { "property1": "string", "property2": "string" }, "first_name": "string", "full_name": "string", "full_name_latin": "string", "gender": "string", "issue_date": "string", "issuing_authority": "string", "issuing_authority_name": "string", "issuing_country": "string", "issuing_place": "string", "issuing_state_code": "string", "last_name": "string", "localized": { "property1": { "property1": "string", "property2": "string" }, "property2": { "property1": "string", "property2": "string" } }, "middle_name": "string", "mrz_code": "string", "mrz_data": { "property1": "string", "property2": "string" }, "mrz_type": "string", "nationality": "string", "nationality_name": "string", "native_full_name": "string", "personal_number": "string", "place_of_birth": "string", "portrait": "string", "portrait_position": { "x1": 0, "x2": 0, "y1": 0, "y2": 0 }, "position": { "x1": 0, "x2": 0, "y1": 0, "y2": 0 }, "profession": "string", "reconciliation": { "canonical_name": { "confidence": 0, "full_name": "string", "given_names": "string", "language": "string", "script": "string", "source": "mrz", "surname": "string" }, "confidence": 0, "conflicts": [ { "code": "name_mismatch", "field": "string", "left_source": "mrz", "right_source": "mrz", "severity": "string" } ], "decision": "accept", "evidence_sufficient": true, "fixable_by_recapture": true, "model": "string", "mrz": { "decision_source": "string", "independent_available": true, "independent_valid": true, "parsed": { "checks": { "property1": { "expected": "string", "observed": "string", "valid": true }, "property2": { "expected": "string", "observed": "string", "valid": true } }, "date_of_birth": "string", "document_number": "string", "expiry_date": "string", "given_names": "string", "layout": "TD1", "nationality": "string", "raw_lines": [ "string" ], "sex": "string", "surname": "string", "valid": true, "validation_complete": true }, "provider_state": "valid", "provider_validation": "string", "shadow_decision_applied": true, "shadow_state": "valid" }, "names": [ { "confidence": 0, "full_name": "string", "given_names": "string", "language": "string", "script": "string", "source": "mrz", "surname": "string" } ], "recommended_action": "continue" }, "tax_number": "string" }, "review_decision": { "automatic_status": "string", "decided_at": "string", "decision": "string", "source": "string" }, "revision": 0, "status": "string" }, "created_at": "string", "extracted_data": { "date_of_birth": "string", "date_of_issue": "string", "document_number": "string", "document_type": "string", "expiry_date": "string", "extended_data": { "property1": "string", "property2": "string" }, "first_name": "string", "full_name": "string", "full_name_latin": "string", "full_name_native": "string", "full_name_original": "string", "gender": "string", "issuing_country": "string", "last_name": "string", "middle_name": "string", "mrz": "string", "nationality": "string", "ocr": { "additional": { "property1": "string", "property2": "string" }, "address": "string", "barcode": { "property1": "string", "property2": "string" }, "booklet_number": "string", "date_of_birth": "string", "document_class": "string", "document_name": "string", "document_number": "string", "document_series": "string", "document_type": "string", "expiry_date": "string", "field_issues": { "property1": "string", "property2": "string" }, "first_name": "string", "full_name": "string", "full_name_latin": "string", "gender": "string", "issue_date": "string", "issuing_authority": "string", "issuing_authority_name": "string", "issuing_country": "string", "issuing_place": "string", "issuing_state_code": "string", "last_name": "string", "localized": { "property1": { "property1": "string", "property2": "string" }, "property2": { "property1": "string", "property2": "string" } }, "middle_name": "string", "mrz_code": "string", "mrz_data": { "property1": "string", "property2": "string" }, "mrz_type": "string", "nationality": "string", "nationality_name": "string", "native_full_name": "string", "personal_number": "string", "place_of_birth": "string", "portrait": "string", "portrait_position": { "x1": 0, "x2": 0, "y1": 0, "y2": 0 }, "position": { "x1": 0, "x2": 0, "y1": 0, "y2": 0 }, "profession": "string", "reconciliation": { "canonical_name": { "confidence": 0, "full_name": "string", "given_names": "string", "language": "string", "script": "string", "source": "mrz", "surname": "string" }, "confidence": 0, "conflicts": [ { "code": "name_mismatch", "field": "string", "left_source": "mrz", "right_source": "mrz", "severity": "string" } ], "decision": "accept", "evidence_sufficient": true, "fixable_by_recapture": true, "model": "string", "mrz": { "decision_source": "string", "independent_available": true, "independent_valid": true, "parsed": { "checks": { "property1": { "expected": "string", "observed": "string", "valid": true }, "property2": { "expected": "string", "observed": "string", "valid": true } }, "date_of_birth": "string", "document_number": "string", "expiry_date": "string", "given_names": "string", "layout": "TD1", "nationality": "string", "raw_lines": [ "string" ], "sex": "string", "surname": "string", "valid": true, "validation_complete": true }, "provider_state": "valid", "provider_validation": "string", "shadow_decision_applied": true, "shadow_state": "valid" }, "names": [ { "confidence": 0, "full_name": "string", "given_names": "string", "language": "string", "script": "string", "source": "mrz", "surname": "string" } ], "recommended_action": "continue" }, "tax_number": "string" }, "place_of_birth": "string" }, "id": "string", "is_current": true, "issuing_country": "string", "pages": [ { "download_url": "string", "download_url_expires_at": "string", "image_id": "string", "side": "string" } ], "reason_codes": [ "string" ], "session_id": "string", "side": "string", "status": "string", "step_id": "string", "type": "string", "verification": { "checks": [ { "is_authentic": true, "liveness_score": 0, "portrait_replace_score": 0, "printed_copy_score": 0, "rejection_reasons": [ "string" ], "screen_replay_score": 0, "similarity_score": 0, "status": "string", "type": "string" } ], "status": "string" } } ]}Коллекции документов и стороны документов
Шаг документа остаётся в совместимом режиме одного документа, пока collection не задан. Параметры collection.min_documents, max_documents (0 означает без ограничений), допустимые страны и типы, а также правила проверки настраиваются в Flow Builder. Пустые списки допустимых значений разрешают все значения, поддерживаемые провайдером; рекомендуемые значения не ограничивают распознавание.
У каждого логического документа есть неизменяемый ID и возрастающая ревизия. Две стороны ID-карты или вида на жительство считаются одним документом. Загрузите оба файла с file_type: document и необязательным file_side: front / back, затем отправьте collection_submit с document_storage_key / file_id и необязательными back_document_storage_key / back_file_id. Старые клиенты коллекций, использующие document_back_storage_key / document_back_file_id, остаются совместимыми; конфликтующие псевдонимы отклоняются. Устаревший execute_step по-прежнему принимает document_back_storage_key / document_back_file_id. Запросы с одним файлом не изменились. Текущий многостраничный эндпоинт KBY AI принимает первое изображение и одно необязательное второе; произвольное число страниц он не принимает.
Результаты сохраняют отдельные утверждения о гражданстве и праве проживания, каждое со ссылкой на ID и ревизию исходного документа. Одна лишь страна выдачи никогда не подтверждает гражданство. Вид на жительство подтверждает указанное право проживания, но не проверенный текущий адрес. Неизвестная личность владельца и противоречивые данные остаются явно отмеченными и обрабатываются согласно настроенному поведению ревью. Документы с ошибками остаются видимыми для ревью и не дают подтверждённых утверждений.
Автоматические запросы документов поддерживают глобальные условия, условия по стране выдачи и гражданству, а также целевые локальные переопределения. Условия внутри одного правила применяются к одному и тому же исходному документу. Источником страны может быть фиксированная страна, страна выдачи исходного документа или гражданство по исходному документу. Требования правила должны быть выполнены до завершения коллекции.
Представления документов в админке показывают для каждого документа страну выдачи, явно указанное гражданство, распознанные поля, исходные стороны и отдельные результаты проверки подлинности. document_order сохраняет стабильную нумерацию, даже когда для совместимых устаревших полей выбран основной документ. doc_liveness_sides хранит оценки лицевой и оборотной сторон отдельно.
Анализ документов KYB архивирует все данные и точные байты HTTP-ответа AI, включая неизвестные поля, с приватной привязкой к клиенту, сессии и выполнению. Кэшированный анализ сохраняет эти байты. Зафиксированная попытка не публикует повторное завершение при повторной доставке сообщения. Авторизованные операторы скачивают архивы через эндпоинт необработанных ответов KYB с повышением уровня доступа для регулируемых медиа и событием аудита. Исторические ответы, которые не архивировались, восстановить нельзя, они отображаются как недоступные.
Ответ админки по документам сессии включает steps[].document_collection, пока коллекция активна, в том числе документы в обработке и с ошибками. Последние ревизии объединяются с текущей попыткой без дублирования исходных файлов. Просроченные документы требуют ревью, если только expiry_check.reject_expired явно не включает отклонение; сбой строгой валидации никогда не понижается другой причиной ревью.
Конечные лимиты коллекции должны оставлять место для исходного документа каждого активного условного правила и запрашиваемых им документов. Правило «вид на жительство — паспорт», требующее один дополнительный документ, требует максимума не менее двух; безусловные требования не резервируют слот под исходный документ. Отключённые правила не занимают ёмкость. Билдер показывает эту ошибку до сохранения, а бэкенд проверяет то же ограничение.