Задачи ревью (manual review API)
Методы Tenant API для серверного ручного ревью: очередь, деталь задачи, assign на API-ключ, approve/reject, комментарии, приоритет, resubmit шага и presigned URL документов.
Эндпоинты рассчитаны на интеграторов, которые ведут ревью во внешней системе (свой back-office или автоматизация). Операторы админ-панели работают через UI — см. Админ → Ревью.
Базовые пути:
| Продукт | Base |
|---|---|
| KYC | /tenant/v1/kyc/review-tasks |
| KYB | /tenant/v1/kyb/review-tasks |
Аутентификация: HMAC-SHA256 с KYC или KYB API-ключом. См. Аутентификация.
Необходимые scopes
| Scope | Доступ |
|---|---|
reviews:read | KYC: очередь, stats, reject-reasons, деталь, комментарии, resubmits |
reviews:write | KYC: assign, approve, reject, comment, priority, request-resubmit |
media:read | KYC: URL документов (вместе с reviews:read) |
kyb.reviews:read | KYB чтение |
kyb.reviews:write | KYB запись |
kyb.media:read | KYB URL документов (вместе с kyb.reviews:read) |
KYC-ключ не может вызывать /kyb/review-tasks/* (HTTP 403), и наоборот.
Мутации атрибутируются API-ключу (actor_type=api_key): assign, комментарии и финальные решения сохраняют id ключа и display name.
Поля ответа для идентичности актора (если заполнены):
| Ресурс | Поля |
|---|---|
| Очередь / деталь задачи | assigned_to, assigned_to_type (admin_user | superadmin_user | api_key), assigned_display_name |
| Деталь после решения | decision_by, decision_by_type, decision_display_name |
| Комментарий | author_id, author_type, author_display_name |
Типовой сценарий
- Подписка на
verification.needs_review— Вебхуки. GET .../review-tasks— очередь (status=pending/in_progress).GET .../review-tasks/{task_id}— деталь иreview_reasons.POST .../assign— взять задачу на текущий API-ключ.- При необходимости
GET .../documents/{document_id}/url. - Решение:
POST .../approvePOST .../rejectс каноническимreason_codeизGET .../reject-reasons- или
POST .../request-resubmitдля одного шага
После финального решения уходят terminal webhook-события (verification.approved / verification.declined).
Очередь
ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
page?integerPage (default 1)
page_size?integerPage size (1-100, default 50)
status?stringComma-separated statuses: pending,assigned,in_progress,awaiting_resubmit,approved,rejected,completed
priority?stringComma-separated priorities: low,medium,high,urgent
flow_id?stringFlow UUID
assigned_to?stringReviewer/API key UUID
session_id?stringSession UUID
applicant_id?stringApplicant UUID
q?stringSearch by external ID/name
date_from?stringFrom (RFC3339)
date_to?stringTo (RFC3339)
sla_status?stringSLA status: breached, warning, ok
sort?stringSort order: priority_desc, sla_asc, created_at_asc, created_at_desc
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
OK
application/json- response
data?array<>pagination?success?booleancurl -X GET 'https://api.onekyc.io/tenant/v1/kyc/review-tasks' \ -H 'X-Timestamp: string'{ "pagination": { "page": 0, "page_size": 0, "total_items": 0, "total_pages": 0 }, "success": true, "data": [ { "applicant_first_name": "string", "applicant_full_name": "string", "applicant_full_name_latin": "string", "applicant_full_name_native": "string", "applicant_full_name_original": "string", "applicant_id": "string", "applicant_last_name": "string", "applicant_middle_name": "string", "applicant_nationality": "string", "assigned_at": "string", "assigned_display_name": "string", "assigned_to": "string", "assigned_to_type": "string", "business_company_name": "string", "business_country": "string", "business_external_id": "string", "business_id": "string", "business_registration_number": "string", "business_tax_number": "string", "created_at": "string", "external_user_id": "string", "flow_id": "string", "flow_name": "string", "id": "string", "priority": 0, "reason": "string", "review_reasons": [ {} ], "reviewer_email": "string", "reviewer_first_name": "string", "reviewer_last_name": "string", "session_created_at": "string", "session_environment": "string", "session_id": "string", "sla_breached": true, "sla_deadline": "string", "started_at": "string", "status": "string", "system_decision": "string", "tenant_id": "string", "verification_result": "string", "verification_score": 0 } ]}KYB: GET /tenant/v1/kyb/review-tasks (те же фильтры; поиск по company/external id).
Алиасы status
| Query | Внутренние статусы |
|---|---|
in_progress | assigned |
completed | approved, rejected |
| прочие | как есть (pending, awaiting_resubmit, …) |
Приоритет
| Значение | Число |
|---|---|
low | 1 |
medium | 2 |
high | 3 |
urgent | 4 |
Stats и причины отклонения
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)
OK
application/json- response
data?success?booleancurl -X GET 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/stats' \ -H 'X-Timestamp: string'{ "success": true, "data": { "avg_time_minutes": 0, "completed_today": 0, "in_progress": 0, "pending": 0 }}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)
OK
application/json- response
data?array<>pagination?success?booleancurl -X GET 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/reject-reasons' \ -H 'X-Timestamp: string'{ "pagination": { "has_more": true, "limit": 0, "next_cursor": "string", "offset": 0, "total": 0 }, "success": true, "data": [ { "category": "string", "code": "string", "label_en": "string", "label_ru": "string" } ]}Канонические коды reject (только их принимает POST .../reject):
blurry_document, expired_document, wrong_document_type, document_mismatch, unreadable_document, face_not_matching, poor_selfie_quality, liveness_failed, face_obscured, sanctions_match, pep_match, adverse_media, suspected_fraud, duplicate_account, incomplete_data, other.
Неканонический reason_code → HTTP 400.
Деталь, комментарии, документы
ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
task_id*stringReview task UUID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
OK
application/json- response
data?success?booleancurl -X GET 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/string' \ -H 'X-Timestamp: string'{ "success": true, "data": { "comments": [ { "author_display_name": "string", "author_id": "string", "author_type": "string", "content": "string", "created_at": "string", "id": "string", "task_id": "string" } ], "task": { "applicant_id": "string", "approval_blocked_reason": "string", "assigned_at": "string", "assigned_display_name": "string", "assigned_to": "string", "assigned_to_type": "string", "completed_at": "string", "created_at": "string", "decision": "string", "decision_at": "string", "decision_by": "string", "decision_by_type": "string", "decision_display_name": "string", "external_user_id": "string", "flow_id": "string", "flow_name": "string", "history": [ { "action": "string", "actor_id": "string", "actor_name": "string", "actor_type": "string", "created_at": "string", "details": { "property1": null, "property2": null }, "id": "string" } ], "id": "string", "notes": "string", "priority": 0, "reason": "string", "reason_details": "string", "reject_reason_code": "string", "resubmit_limit_override": 0, "review_reasons": [ {} ], "session_created_at": "string", "session_entity_type": "string", "session_environment": "string", "session_id": "string", "session_status": "string", "status": "string", "system_decision": "string", "tenant_id": "string" } }}У неназначенных задач нет assigned_to / assigned_to_type / assigned_display_name (не подставляется admin_user). После assign/decision type — одно из admin_user | superadmin_user | api_key.
ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
task_id*stringReview task UUID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
OK
application/json- response
data?array<>pagination?success?booleancurl -X GET 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/string/comments' \ -H 'X-Timestamp: string'{ "pagination": { "has_more": true, "limit": 0, "next_cursor": "string", "offset": 0, "total": 0 }, "success": true, "data": [ { "author_display_name": "string", "author_id": "string", "author_type": "string", "content": "string", "created_at": "string", "id": "string", "task_id": "string" } ]}ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
task_id*stringReview task UUID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
Comment payload
application/json- body
content?stringContent is the comment text (required, non-empty after trim).
OK
application/json- response
data?success?booleancurl -X POST 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/string/comments' \ -H 'X-Timestamp: string' \ -H 'Content-Type: application/json' \ -d '{}'{ "success": true, "data": { "author_display_name": "string", "author_id": "string", "author_type": "string", "comment_id": "string", "content": "string", "created_at": "string", "message": "string", "task_id": "string" }}Поле текста комментария — content (не body). Пример: {"content":"Нужно более чёткое фото паспорта"}. В ответе: author_id, author_type (api_key для HMAC), author_display_name.
ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
task_id*stringReview task UUID
document_id*stringDocument ID or storage key suffix
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
OK
application/json- response
data?unknownsuccess?booleancurl -X GET 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/string/documents/string/url' \ -H 'X-Timestamp: string'{ "data": null, "success": true}Мутации: assign, priority, decide
ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
task_id*stringReview task UUID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
OK
application/json- response
data?unknownsuccess?booleancurl -X POST 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/string/assign' \ -H 'X-Timestamp: string'{ "data": null, "success": true}Assign возможен для pending и awaiting_resubmit. Задача назначается на текущий API-ключ.
ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
task_id*stringReview task UUID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
Priority payload
application/json- body
priority?stringOK
application/json- response
data?unknownsuccess?booleancurl -X PATCH 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/string/priority' \ -H 'X-Timestamp: string' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": null, "success": true}ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
task_id*stringReview task UUID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
Optional comment and optimistic lock timestamp
application/json- body
comment?stringif_unmodified_since?stringOK
application/json- response
data?unknownsuccess?booleancurl -X POST 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/string/approve' \ -H 'X-Timestamp: string' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": null, "success": true}ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
task_id*stringReview task UUID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
Reject payload
application/json- body
comment?stringif_unmodified_since?stringreason_code?stringOK
application/json- response
data?unknownsuccess?booleancurl -X POST 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/string/reject' \ -H 'X-Timestamp: string' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": null, "success": true}Опционально: if_unmodified_since (RFC3339) для optimistic concurrency.
Resubmit
ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
task_id*stringReview task UUID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
Resubmit payload
application/json- body
client_message?stringinternal_notes?stringreason_code?stringrequest_id?stringscope?stringstep_id?stringOK
application/json- response
data?success?booleancurl -X POST 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/string/request-resubmit' \ -H 'X-Timestamp: string' \ -H 'Content-Type: application/json' \ -d '{}'{ "success": true, "data": { "clientMessage": "string", "createdAt": "string", "deliveredAt": "string", "deliveryChannel": "string", "expiresAt": "string", "fulfilledAt": "string", "id": "string", "internalNotes": "string", "reasonCode": "string", "requestedBy": "string", "requestedByDisplayName": "string", "requestedByType": "string", "scope": "string", "sessionID": "string", "status": "string", "stepID": "string", "taskID": "string", "tenantID": "string", "updatedAt": "string" }}ApiKeyAuthAuthorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
task_id*stringReview task UUID
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
OK
application/json- response
data?array<>pagination?success?booleancurl -X GET 'https://api.onekyc.io/tenant/v1/kyc/review-tasks/string/resubmits' \ -H 'X-Timestamp: string'{ "pagination": { "has_more": true, "limit": 0, "next_cursor": "string", "offset": 0, "total": 0 }, "success": true, "data": [ { "clientMessage": "string", "createdAt": "string", "deliveredAt": "string", "deliveryChannel": "string", "expiresAt": "string", "fulfilledAt": "string", "id": "string", "internalNotes": "string", "reasonCode": "string", "requestedBy": "string", "requestedByDisplayName": "string", "requestedByType": "string", "scope": "string", "sessionID": "string", "status": "string", "stepID": "string", "taskID": "string", "tenantID": "string", "updatedAt": "string" } ]}Коды resubmit (качество шага), не путать с reject reasons: illegible, blurry, cropped, glare, wrong_document, expired_document, partial.
Лимиты: ≤ 3 на сессию, TTL 7 дней, один active request на пару (session, step). Вебхуки: Manual Review Resubmit.
KYB
Зеркальные методы: /tenant/v1/kyb/review-tasks со scopes kyb.reviews:* и kyb.media:read. См. KYB API — Справочник и OpenAPI.
Только admin (не Tenant API)
- reassign / unassign другому оператору
- delegate команде OneKYC
- cancel resubmit
- вспомогательные list resubmittable steps UI-эндпоинты консоли