К содержимому
OneKYC
Tenant API (KYC)

Документы и медиа

Обновлено:

Tenant API предоставляет эндпоинты для получения информации о поддерживаемых типах документов и доступа к загруженным медиафайлам (фотографии документов, селфи). Загрузка файлов осуществляется автоматически в процессе прохождения верификации на стороне OneKYC.

Поддерживаемые типы документов

Возвращает перечень типов документов, поддерживаемых платформой, с указанием стран и допустимых форматов. Требуемый scope: documents:read.

GET
/v1/kyc/documents/supported

Authorization

ApiKeyAuth
headerAuthorization<token>

HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.

Header Parameters

X-Timestamp*string

Unix timestamp (seconds, max 5 min drift)

Response Body

Supported documents list

application/json
  1. response
data?unknown
success?boolean
Example Request
curl -X GET 'https://api.onekyc.io/tenant/v1/kyc/documents/supported' \  -H 'X-Timestamp: string'
Example Response
{  "data": null,  "success": true}

Получение медиафайла

Возвращает подписанную ссылку для скачивания медиафайла по его идентификатору. Требуемый scope: media:read.

GET
/v1/kyc/media/{media_id}

Authorization

ApiKeyAuth
headerAuthorization<token>

HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.

Path Parameters

media_id*string

Media UUID

Header Parameters

X-Timestamp*string

Unix timestamp (seconds, max 5 min drift)

Response Body

Presigned URL

application/json
  1. response
data?unknown
success?boolean
Example Request
curl -X GET 'https://api.onekyc.io/tenant/v1/kyc/media/string' \  -H 'X-Timestamp: string'
Example Response
{  "data": null,  "success": true}

Примечание. Идентификаторы медиафайлов содержатся в данных аппликанта и в списке документов аппликанта. Подписанная ссылка на медиафайл имеет ограниченный срок действия.

Как скачать файлы после получения вебхука

При получении вебхука (например, session.completed или verification.approved) в payload присутствуют:

  • applicant_id — идентификатор аппликанта
  • media — объект со storage keys (информационные, не являются идентификаторами для API)

Рекомендуемый порядок:

  1. Получить данные аппликанта — 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 — срок действия ссылок
  2. Или получить список документов — GET /v1/kyc/applicants/{applicant_id}/documents. Если у вас есть только ваш внешний идентификатор, используйте GET /v1/kyc/applicants/external/{external_id}/documents. Ответ содержит id каждого документа (UUID), который можно использовать для GET /v1/kyc/media/{media_id}.

  3. Скачать файл по подписанной ссылке (HTTP GET, без аутентификации). Ссылка действительна ограниченное время.

Важно. Поле media в вебхуке содержит внутренние storage keys, а не идентификаторы для API. Для скачивания используйте подписанные ссылки из ответа GET /v1/kyc/applicants/{applicant_id}.

Документы аппликанта

Возвращает список документов, загруженных конкретным аппликантом в рамках верификации. Требуемый scope: documents:read.

GET
/v1/kyc/applicants/{applicant_id}/documents

Authorization

ApiKeyAuth
headerAuthorization<token>

HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.

Path Parameters

applicant_id*string

Applicant UUID

Header Parameters

X-Timestamp*string

Unix timestamp (seconds, max 5 min drift)

Response Body

Documents list

application/json
  1. response
data?array<>
pagination?
success?boolean
Example Request
curl -X GET 'https://api.onekyc.io/tenant/v1/kyc/applicants/string/documents' \  -H 'X-Timestamp: string'
Example Response
{  "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.

GET
/v1/kyc/applicants/external/{external_id}/documents

Authorization

ApiKeyAuth
headerAuthorization<token>

HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.

Path Parameters

external_id*string

External user ID

Header Parameters

X-Timestamp*string

Unix timestamp (seconds, max 5 min drift)

Response Body

Documents list

application/json
  1. response
data?array<>
pagination?
success?boolean
Example Request
curl -X GET 'https://api.onekyc.io/tenant/v1/kyc/applicants/external/string/documents' \  -H 'X-Timestamp: string'
Example Response
{  "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 явно не включает отклонение; сбой строгой валидации никогда не понижается другой причиной ревью.

Конечные лимиты коллекции должны оставлять место для исходного документа каждого активного условного правила и запрашиваемых им документов. Правило «вид на жительство — паспорт», требующее один дополнительный документ, требует максимума не менее двух; безусловные требования не резервируют слот под исходный документ. Отключённые правила не занимают ёмкость. Билдер показывает эту ошибку до сохранения, а бэкенд проверяет то же ограничение.

На этой странице