{ "openapi": "3.0.0", "info": { "contact": { "email": "support.invalid", "name": "API Support", "url": "https://example.invalid" }, "description": "B2B API for KYC/KYB integration. Auth: HMAC-SHA256.\nAuth: Authorization header with HMAC-SHA256 Credential=, Signature=. X-Timestamp header (Unix seconds, max 5 min drift).", "license": { "name": "Proprietary", "url": "https://example.invalid/terms" }, "termsOfService": "https://example.invalid/terms", "title": "Tenant API", "version": "1.0" }, "paths": { "/v1/kyb/applicants/external/{external_id}/documents": { "get": { "description": "Returns documents for a KYB-related applicant, such as a beneficiary KYC session, resolved by external_id.\nRequires KYB API key and kyb.documents:read scope.\nUse /v1/kyb/businesses/external/{external_id}/document for the company registration document itself.", "operationId": "getKYBApplicantDocumentsByExternalID", "parameters": [ { "description": "External user ID", "in": "path", "name": "external_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Documents list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/ApplicantDocumentPublicResponse" }, "type": "array" } }, "type": "object" } ] } } } }, "400": { "description": "External ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (KYB key or kyb.documents:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Applicant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYB applicant documents by external ID", "tags": [ "KYB Businesses" ] } }, "/v1/kyb/audit": { "get": { "description": "Returns paginated audit log for KYB operations. Requires KYB key and kyb.audit:read scope.", "operationId": "listKYBAuditLog", "parameters": [ { "description": "Page (default 1)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Page size (1-100, default 50)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Filter by action", "in": "query", "name": "action", "schema": { "type": "string" } }, { "description": "Filter by actor UUID", "in": "query", "name": "actorId", "schema": { "type": "string" } }, { "description": "From (RFC3339)", "in": "query", "name": "dateFrom", "schema": { "type": "string" } }, { "description": "To (RFC3339)", "in": "query", "name": "dateTo", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paged audit log items", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PagedListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/AuditLogItemResp" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (KYB key or kyb.audit:read scope required)", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List KYB audit log", "tags": [ "KYB Audit" ] } }, "/v1/kyb/businesses": { "get": { "description": "Returns a paginated list of companies. Requires KYB key and businesses:read scope.", "operationId": "listKYBBusinesses", "parameters": [ { "description": "Page (1-based, default 1)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Page size (1-100, default 50)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Filter: pending, verified, rejected, review", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Filter by country (ISO 3166-1 alpha-2)", "in": "query", "name": "country", "schema": { "type": "string" } }, { "description": "Search by company name or registration number", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Filter by registration number", "in": "query", "name": "registration_number", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of companies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBusinessesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (KYB key or scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List businesses (KYB)", "tags": [ "KYB Businesses" ] } }, "/v1/kyb/businesses/{business_id}": { "delete": { "description": "Submits a deletion request for business data. Requires KYB key and businesses:write scope. Deletion is executed after platform approval.", "operationId": "deleteKYBBusinessData", "parameters": [ { "description": "Business UUID", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Deletion request created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/DeletionRequest" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid business ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Pending deletion request already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Deletion service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Request business data deletion (KYB/GDPR)", "tags": [ "KYB Businesses" ] }, "get": { "description": "Returns a single company by UUID. Requires businesses:read.", "operationId": "getKYBBusiness", "parameters": [ { "description": "Business UUID", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGetResponse" } } } }, "400": { "description": "Invalid business ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get business by ID (KYB)", "tags": [ "KYB Businesses" ] } }, "/v1/kyb/businesses/{business_id}/history": { "get": { "description": "Returns status change history for the business, derived from sessions (max 100 most recent). Requires KYB key and businesses:read scope.", "operationId": "getKYBBusinessHistory", "parameters": [ { "description": "Business UUID", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "History list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/BusinessHistoryItem" }, "type": "array" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid business ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get business history (KYB)", "tags": [ "KYB Businesses" ] } }, "/v1/kyb/businesses/{business_id}/sessions": { "get": { "description": "Returns paginated KYB sessions for the company. Requires kyb.sessions:read.", "operationId": "listKYBBusinessSessions", "parameters": [ { "description": "Business UUID", "in": "path", "name": "business_id", "required": true, "schema": { "type": "string" } }, { "description": "Page (default 1)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Page size (1-100, default 20)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sessions list with total", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSessionsSuccessResponse" } } } }, "400": { "description": "Invalid business ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List business verification sessions (KYB)", "tags": [ "KYB Businesses" ] } }, "/v1/kyb/businesses/external/{external_id}": { "get": { "description": "Returns a company by your external_user_id. Requires businesses:read.", "operationId": "getKYBBusinessByExternalID", "parameters": [ { "description": "Your external company/user ID", "in": "path", "name": "external_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessGetResponse" } } } }, "400": { "description": "External ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get business by external ID (KYB)", "tags": [ "KYB Businesses" ] } }, "/v1/kyb/businesses/external/{external_id}/document": { "get": { "description": "Returns a time-limited presigned URL for the business document uploaded by the user during KYB verification.\nRequires KYB key and kyb.documents:read scope.", "operationId": "getKYBBusinessDocumentURLByExternalID", "parameters": [ { "description": "Your external company/user ID", "in": "path", "name": "external_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Presigned document URL", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/BusinessDocumentURLResponse" } }, "type": "object" } ] } } } }, "400": { "description": "External ID required or applicant external_id used for business document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (KYB key or kyb.documents:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Business or document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Presigned URL unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get business document URL by external ID (KYB)", "tags": [ "KYB Businesses" ] } }, "/v1/kyb/media/{media_id}": { "get": { "description": "Returns a presigned URL for a media asset (document image, selfie). Requires KYB key and kyb.media:read scope.", "operationId": "getKYBMediaURL", "parameters": [ { "description": "Media UUID", "in": "path", "name": "media_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Presigned URL", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/MediaURLResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid media ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (KYB key or kyb.media:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get media presigned URL (KYB)", "tags": [ "KYB Media" ] } }, "/v1/kyb/metrics/activity": { "get": { "description": "Returns recent KYB activity items (limit 1–50, default 10). Requires KYB key and kyb.metrics:read scope.", "operationId": "getKYBMetricsActivity", "parameters": [ { "description": "Max items (1-50, default 10)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Activity items", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/ActivityItem" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYB recent activity", "tags": [ "KYB Metrics" ] } }, "/v1/kyb/metrics/chart": { "get": { "description": "Returns time-series chart data for KYB verifications. Requires KYB key and kyb.metrics:read scope.", "operationId": "getKYBMetricsChart", "parameters": [ { "description": "7d, 30d, 90d, 12m", "in": "query", "name": "period", "schema": { "type": "string" } }, { "description": "Filter by flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chart data", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/ChartDataPoint" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYB metrics chart data", "tags": [ "KYB Metrics" ] } }, "/v1/kyb/metrics/export": { "get": { "description": "Returns KYB stats and chart data as CSV file. Requires KYB key and kyb.metrics:read scope.", "operationId": "exportKYBMetrics", "parameters": [ { "description": "7d, 30d, 90d, 12m", "in": "query", "name": "period", "schema": { "type": "string" } }, { "description": "Filter by flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV file", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Export KYB metrics as CSV", "tags": [ "KYB Metrics" ] } }, "/v1/kyb/metrics/funnel": { "get": { "description": "Returns funnel step counts for KYB sessions. Requires KYB key and kyb.metrics:read scope.", "operationId": "getKYBMetricsFunnel", "parameters": [ { "description": "7d, 30d, 90d, 12m", "in": "query", "name": "period", "schema": { "type": "string" } }, { "description": "Filter by flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Funnel steps", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/FunnelStep" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYB funnel data", "tags": [ "KYB Metrics" ] } }, "/v1/kyb/metrics/realtime": { "get": { "description": "Returns active KYB sessions count and sessions in the last hour. Requires KYB key and kyb.metrics:read scope.", "operationId": "getKYBMetricsRealtime", "parameters": [ { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Realtime stats", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/RealtimeStats" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYB realtime metrics", "tags": [ "KYB Metrics" ] } }, "/v1/kyb/metrics/stats": { "get": { "description": "Returns aggregate KYB metrics: totalSessions, completedVerifications, approvalRate. Requires KYB key and kyb.metrics:read scope.", "operationId": "getKYBMetricsStats", "parameters": [ { "description": "7d, 30d, 90d, 12m (default 30d)", "in": "query", "name": "period", "schema": { "type": "string" } }, { "description": "Filter by flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stats", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/Stats" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (KYB key or kyb.metrics:read scope required)", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYB metrics stats", "tags": [ "KYB Metrics" ] } }, "/v1/kyb/review-tasks": { "get": { "description": "Returns a paginated manual review queue. Requires KYB API key and kyb.reviews:read scope.", "operationId": "listKYBReviewTasks", "parameters": [ { "description": "Page (default 1)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Page size (1-100, default 50)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Comma-separated statuses: pending,assigned,in_progress,awaiting_resubmit,approved,rejected,completed", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Comma-separated priorities: low,medium,high,urgent", "in": "query", "name": "priority", "schema": { "type": "string" } }, { "description": "Flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Reviewer/API key UUID", "in": "query", "name": "assigned_to", "schema": { "type": "string" } }, { "description": "Session UUID", "in": "query", "name": "session_id", "schema": { "type": "string" } }, { "description": "Search by external ID/company", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "From (RFC3339)", "in": "query", "name": "date_from", "schema": { "type": "string" } }, { "description": "To (RFC3339)", "in": "query", "name": "date_to", "schema": { "type": "string" } }, { "description": "SLA status: breached, warning, ok", "in": "query", "name": "sla_status", "schema": { "type": "string" } }, { "description": "Sort order: priority_desc, sla_asc, created_at_asc, created_at_desc", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PagedListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/QueueItem" }, "type": "array" } }, "type": "object" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List review tasks (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/review-tasks/{task_id}": { "get": { "description": "Returns task detail and comments. Requires KYB API key and kyb.reviews:read scope.", "operationId": "getKYBReviewTask", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/tenantReviewTaskResponse" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get review task (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/review-tasks/{task_id}/approve": { "post": { "description": "Completes review task as approved. Requires KYB API key and kyb.reviews:write scope.", "operationId": "approveKYBReviewTask", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/tenantReviewDecisionRequest" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Approve review task (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/review-tasks/{task_id}/assign": { "post": { "description": "Assigns the task to the authenticated API key. Requires KYB API key and kyb.reviews:write scope.", "operationId": "assignKYBReviewTask", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Assign review task to current API key (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/review-tasks/{task_id}/comments": { "get": { "description": "Returns comments for a review task. Requires KYB API key and kyb.reviews:read scope.", "operationId": "listKYBReviewComments", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/CommentRow" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List review comments (KYB)", "tags": [ "KYB Review" ] }, "post": { "description": "Adds a comment authored by the authenticated API key. Publishes kyb.review.comment.created. Comments are client-visible. Requires KYB API key and kyb.reviews:write scope.", "operationId": "addKYBReviewComment", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/tenantReviewCommentRequest" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/tenantReviewCommentResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Add review comment (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/review-tasks/{task_id}/documents/{document_id}/url": { "get": { "description": "Returns a presigned document URL. Requires KYB API key plus kyb.reviews:read and kyb.media:read scopes.", "operationId": "getKYBReviewDocumentURL", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Document ID or storage key suffix", "in": "path", "name": "document_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get review document URL (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/review-tasks/{task_id}/priority": { "patch": { "description": "Updates review task priority. Requires KYB API key and kyb.reviews:write scope.", "operationId": "updateKYBReviewPriority", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/tenantPriorityRequest" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Update review task priority (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/review-tasks/{task_id}/reject": { "post": { "description": "Completes review task as rejected with a canonical reason. Requires KYB API key and kyb.reviews:write scope.", "operationId": "rejectKYBReviewTask", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/tenantRejectRequest" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Reject review task (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/review-tasks/{task_id}/request-resubmit": { "post": { "description": "Requests a step or full KYB resubmit. Requires KYB API key and kyb.reviews:write scope.", "operationId": "requestKYBReviewResubmit", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/tenantResubmitRequest" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/Request" } }, "type": "object" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Request resubmit from review (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/review-tasks/{task_id}/resubmits": { "get": { "description": "Returns resubmit requests for a review task. Requires KYB API key and kyb.reviews:read scope.", "operationId": "listKYBReviewResubmits", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/Request" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List review resubmits (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/review-tasks/reject-reasons": { "get": { "description": "Returns canonical rejection reasons. Requires KYB API key and kyb.reviews:read scope.", "operationId": "getKYBReviewRejectReasons", "parameters": [ { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/RejectReasonRow" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List review reject reasons (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/review-tasks/stats": { "get": { "description": "Returns review queue counters. Requires KYB API key and kyb.reviews:read scope.", "operationId": "getKYBReviewStats", "parameters": [ { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/StatsRow" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get review stats (KYB)", "tags": [ "KYB Review" ] } }, "/v1/kyb/verification-links": { "get": { "description": "Returns paginated list of KYB verification links. Requires KYB key and kyb.verification-links:read scope.", "operationId": "listKYBVerificationLinks", "parameters": [ { "description": "Page (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Page size (1-100)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Filter by status (active, consumed, revoked)", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Filter by external user ID", "in": "query", "name": "external_user_id", "schema": { "type": "string" } }, { "description": "Filter by external reference", "in": "query", "name": "external_reference", "schema": { "type": "string" } }, { "description": "Filter by flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Sort field (default created_at)", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "Sort order: asc, desc (default desc)", "in": "query", "name": "sort_order", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification links", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/ListLinksResponse" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (KYB key or kyb.verification-links:read scope required)", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List KYB verification links", "tags": [ "KYB Verification Links" ] }, "post": { "description": "Creates a new KYB verification link (flow_id required). Requires KYB key and kyb.verification-links:write scope.", "operationId": "createKYBVerificationLink", "parameters": [ { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/CreateLinkRequest" }, "responses": { "201": { "description": "Created or reused link", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/CreateLinkResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (KYB key or kyb.verification-links:write scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "An existing verification is awaiting manual review (session_review_pending)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create KYB verification link", "tags": [ "KYB Verification Links" ] } }, "/v1/kyb/verification-links/{id}": { "get": { "description": "Returns a single KYB verification link by UUID. Requires KYB key and kyb.verification-links:read scope.", "operationId": "getKYBVerificationLink", "parameters": [ { "description": "Link UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification link details", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/VerificationLinkResp" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid ID", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYB verification link by ID", "tags": [ "KYB Verification Links" ] } }, "/v1/kyb/verification-links/{id}/qr": { "get": { "description": "Returns PNG image of QR code for the KYB link URL. Requires KYB key and kyb.verification-links:read scope.", "operationId": "getKYBVerificationLinkQR", "parameters": [ { "description": "Link UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "QR size in pixels (1-1024, default 256)", "in": "query", "name": "size", "schema": { "type": "integer" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PNG image", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get QR code for KYB verification link", "tags": [ "KYB Verification Links" ] } }, "/v1/kyb/verification-links/{id}/revoke": { "post": { "description": "Revokes an active KYB link so it can no longer be used. Requires KYB key and kyb.verification-links:write scope.", "operationId": "revokeKYBVerificationLink", "parameters": [ { "description": "Link UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/RevokeReasonBody" }, "responses": { "200": { "description": "Revoked link info", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/RevokeLinkResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Revoke KYB verification link", "tags": [ "KYB Verification Links" ] } }, "/v1/kyb/verification-links/batch": { "post": { "description": "Creates multiple KYB verification links in a single request (max 500). Requires KYB key and kyb.verification-links:write scope.", "operationId": "batchCreateKYBVerificationLinks", "parameters": [ { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/BatchCreateRequest" }, "responses": { "200": { "description": "Created links", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/BatchCreateResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (KYB key or kyb.verification-links:write scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Batch create KYB verification links", "tags": [ "KYB Verification Links" ] } }, "/v1/kyc/applicants": { "get": { "description": "Returns a paginated list of applicants. Requires KYC API key and applicants:read scope.", "operationId": "listKYCApplicants", "parameters": [ { "description": "Limit (1-100, default 50)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Offset (default 0)", "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "Filter by verification status", "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "pending", "verified", "rejected", "review" ] } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Applicants list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/ApplicantResponse" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (applicants:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List applicants (KYC)", "tags": [ "KYC Applicants" ] } }, "/v1/kyc/applicants/{applicant_id}": { "delete": { "description": "Submits deletion request for applicant PII. Requires KYC API key and applicants:write scope.", "operationId": "deleteKYCApplicantData", "parameters": [ { "description": "Applicant UUID", "in": "path", "name": "applicant_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Deletion request created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/DeletionRequest" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid applicant ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (applicants:write scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Pending deletion request already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Deletion service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Request applicant data deletion (KYC/GDPR)", "tags": [ "KYC Applicants" ] }, "get": { "description": "Returns a single applicant by UUID. Requires KYC API key and applicants:read scope.", "operationId": "getKYCApplicant", "parameters": [ { "description": "Applicant UUID", "in": "path", "name": "applicant_id", "required": true, "schema": { "type": "string" } }, { "description": "Include document recognition, personal info and sessions (default false)", "in": "query", "name": "detailed", "schema": { "type": "boolean" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Applicant profile; detailed fields are included only with detailed=true", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/ApplicantDetailResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid applicant ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (applicants:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get applicant by ID (KYC)", "tags": [ "KYC Applicants" ] } }, "/v1/kyc/applicants/{applicant_id}/aml": { "get": { "description": "Returns AML screening result if enabled. Requires KYC API key and verifications:read scope.", "operationId": "getKYCApplicantAML", "parameters": [ { "description": "Applicant UUID", "in": "path", "name": "applicant_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/ApplicantAMLResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid applicant ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (verifications:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get applicant AML result (KYC)", "tags": [ "KYC Applicants" ] } }, "/v1/kyc/applicants/{applicant_id}/documents": { "get": { "description": "Returns list of documents for the applicant. Requires KYC API key and documents:read scope.", "operationId": "getKYCApplicantDocuments", "parameters": [ { "description": "Applicant UUID", "in": "path", "name": "applicant_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Documents list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/ApplicantDocumentPublicResponse" }, "type": "array" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid applicant ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (documents:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get applicant documents (KYC)", "tags": [ "KYC Applicants" ] } }, "/v1/kyc/applicants/{applicant_id}/history": { "get": { "description": "Returns status change history for the applicant. Requires KYC API key and applicants:read scope.", "operationId": "getKYCApplicantHistory", "parameters": [ { "description": "Applicant UUID", "in": "path", "name": "applicant_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "History list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/ApplicantHistoryEntry" }, "type": "array" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid applicant ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (applicants:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get applicant history (KYC)", "tags": [ "KYC Applicants" ] } }, "/v1/kyc/applicants/{applicant_id}/sessions": { "get": { "description": "Returns all verification sessions for the applicant. Requires KYC API key and applicants:read scope.", "operationId": "getKYCApplicantSessions", "parameters": [ { "description": "Applicant UUID", "in": "path", "name": "applicant_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sessions list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/ApplicantSessionResponse" }, "type": "array" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid applicant ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (applicants:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get applicant sessions (KYC)", "tags": [ "KYC Applicants" ] } }, "/v1/kyc/applicants/{applicant_id}/verification": { "get": { "description": "Returns verification outcome and details. Requires KYC API key and verifications:read scope.", "operationId": "getKYCApplicantVerification", "parameters": [ { "description": "Applicant UUID", "in": "path", "name": "applicant_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/ApplicantVerificationResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid applicant ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (verifications:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get applicant verification result (KYC)", "tags": [ "KYC Applicants" ] } }, "/v1/kyc/applicants/external/{external_id}": { "get": { "description": "Returns an applicant by external_user_id. Requires KYC API key and applicants:read scope.", "operationId": "getKYCApplicantByExternalID", "parameters": [ { "description": "External user ID", "in": "path", "name": "external_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/ApplicantResponse" } }, "type": "object" } ] } } } }, "400": { "description": "External ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (applicants:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get applicant by external ID (KYC)", "tags": [ "KYC Applicants" ] } }, "/v1/kyc/applicants/external/{external_id}/documents": { "get": { "description": "Returns documents for the applicant resolved by external_id, including presigned `download_url` per page.\nRequires KYC API key and documents:read scope.\nURLs expire after `download_url_expires_at`; when expired, fetch a fresh URL via GET /v1/kyc/media/{media_id}.", "operationId": "getKYCApplicantDocumentsByExternalID", "parameters": [ { "description": "External user ID", "in": "path", "name": "external_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Documents list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/ApplicantDocumentPublicResponse" }, "type": "array" } }, "type": "object" } ] } } } }, "400": { "description": "External ID required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (documents:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Applicant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get applicant documents by external ID (KYC)", "tags": [ "KYC Applicants" ] } }, "/v1/kyc/audit": { "get": { "description": "Returns paginated audit log for KYC operations. Requires KYC API key and audit:read scope.", "operationId": "listKYCAuditLog", "parameters": [ { "description": "Page (default 1)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Page size (1-100, default 50)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Filter by action", "in": "query", "name": "action", "schema": { "type": "string" } }, { "description": "Filter by actor UUID", "in": "query", "name": "actorId", "schema": { "type": "string" } }, { "description": "From (RFC3339)", "in": "query", "name": "dateFrom", "schema": { "type": "string" } }, { "description": "To (RFC3339)", "in": "query", "name": "dateTo", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paged audit log items", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PagedListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/AuditLogItemResp" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (audit:read scope required)", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List KYC audit log", "tags": [ "KYC Audit" ] } }, "/v1/kyc/documents/supported": { "get": { "description": "Returns list of supported document types for verification. Requires KYC API key and documents:read scope.", "operationId": "getKYCDocumentsSupported", "parameters": [ { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Supported documents list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (documents:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get supported documents (KYC)", "tags": [ "KYC Documents" ] } }, "/v1/kyc/media/{media_id}": { "get": { "description": "Returns a presigned URL for a media asset. Requires KYC API key and media:read scope.", "operationId": "getKYCMediaURL", "parameters": [ { "description": "Media UUID", "in": "path", "name": "media_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Presigned URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Invalid media ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (media:read scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get media presigned URL (KYC)", "tags": [ "KYC Media" ] } }, "/v1/kyc/metrics/activity": { "get": { "description": "Returns recent KYC activity items (limit 1–50, default 10). Requires KYC API key and metrics:read scope.", "operationId": "getKYCMetricsActivity", "parameters": [ { "description": "Max items (1-50, default 10)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Activity items", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/ActivityItem" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYC recent activity", "tags": [ "KYC Metrics" ] } }, "/v1/kyc/metrics/chart": { "get": { "description": "Returns time-series chart data for KYC verifications. Requires KYC API key and metrics:read scope.", "operationId": "getKYCMetricsChart", "parameters": [ { "description": "7d, 30d, 90d, 12m", "in": "query", "name": "period", "schema": { "type": "string" } }, { "description": "Filter by flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chart data", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/ChartDataPoint" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYC metrics chart data", "tags": [ "KYC Metrics" ] } }, "/v1/kyc/metrics/export": { "get": { "description": "Returns KYC stats and chart data as CSV file. Requires KYC API key and metrics:read scope.", "operationId": "exportKYCMetrics", "parameters": [ { "description": "7d, 30d, 90d, 12m", "in": "query", "name": "period", "schema": { "type": "string" } }, { "description": "Filter by flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV file", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "text/csv": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Export KYC metrics as CSV", "tags": [ "KYC Metrics" ] } }, "/v1/kyc/metrics/funnel": { "get": { "description": "Returns funnel step counts for KYC sessions. Requires KYC API key and metrics:read scope.", "operationId": "getKYCMetricsFunnel", "parameters": [ { "description": "7d, 30d, 90d, 12m", "in": "query", "name": "period", "schema": { "type": "string" } }, { "description": "Filter by flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Funnel steps", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/FunnelStep" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYC funnel data", "tags": [ "KYC Metrics" ] } }, "/v1/kyc/metrics/realtime": { "get": { "description": "Returns active KYC sessions count and sessions in the last hour. Requires KYC API key and metrics:read scope.", "operationId": "getKYCMetricsRealtime", "parameters": [ { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Realtime stats", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/RealtimeStats" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYC realtime metrics", "tags": [ "KYC Metrics" ] } }, "/v1/kyc/metrics/stats": { "get": { "description": "Returns aggregate verification metrics. Requires KYC API key and metrics:read scope.", "operationId": "getKYCMetricsStats", "parameters": [ { "description": "7d, 30d, 90d, 12m (default 30d)", "in": "query", "name": "period", "schema": { "type": "string" } }, { "description": "Filter by flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stats", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/Stats" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (metrics:read scope required)", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYC metrics stats", "tags": [ "KYC Metrics" ] } }, "/v1/kyc/review-tasks": { "get": { "description": "Returns a paginated manual review queue. Requires KYC API key and reviews:read scope.", "operationId": "listKYCReviewTasks", "parameters": [ { "description": "Page (default 1)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Page size (1-100, default 50)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Comma-separated statuses: pending,assigned,in_progress,awaiting_resubmit,approved,rejected,completed", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Comma-separated priorities: low,medium,high,urgent", "in": "query", "name": "priority", "schema": { "type": "string" } }, { "description": "Flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Reviewer/API key UUID", "in": "query", "name": "assigned_to", "schema": { "type": "string" } }, { "description": "Session UUID", "in": "query", "name": "session_id", "schema": { "type": "string" } }, { "description": "Applicant UUID", "in": "query", "name": "applicant_id", "schema": { "type": "string" } }, { "description": "Search by external ID/name", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "From (RFC3339)", "in": "query", "name": "date_from", "schema": { "type": "string" } }, { "description": "To (RFC3339)", "in": "query", "name": "date_to", "schema": { "type": "string" } }, { "description": "SLA status: breached, warning, ok", "in": "query", "name": "sla_status", "schema": { "type": "string" } }, { "description": "Sort order: priority_desc, sla_asc, created_at_asc, created_at_desc", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PagedListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/QueueItem" }, "type": "array" } }, "type": "object" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List review tasks (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/review-tasks/{task_id}": { "get": { "description": "Returns task detail and comments. Requires KYC API key and reviews:read scope.", "operationId": "getKYCReviewTask", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/tenantReviewTaskResponse" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get review task (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/review-tasks/{task_id}/approve": { "post": { "description": "Completes review task as approved. Requires KYC API key and reviews:write scope.", "operationId": "approveKYCReviewTask", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/tenantReviewDecisionRequest" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Approve review task (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/review-tasks/{task_id}/assign": { "post": { "description": "Assigns the task to the authenticated API key. Requires KYC API key and reviews:write scope.", "operationId": "assignKYCReviewTask", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Assign review task to current API key (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/review-tasks/{task_id}/comments": { "get": { "description": "Returns comments for a review task. Requires KYC API key and reviews:read scope.", "operationId": "listKYCReviewComments", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/CommentRow" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List review comments (KYC)", "tags": [ "KYC Review" ] }, "post": { "description": "Adds a comment authored by the authenticated API key. Publishes verification.comment.created. Comments are client-visible. Requires KYC API key and reviews:write scope.", "operationId": "addKYCReviewComment", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/tenantReviewCommentRequest" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/tenantReviewCommentResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Add review comment (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/review-tasks/{task_id}/documents/{document_id}/url": { "get": { "description": "Returns a presigned document URL. Requires KYC API key plus reviews:read and media:read scopes.", "operationId": "getKYCReviewDocumentURL", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Document ID or storage key suffix", "in": "path", "name": "document_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get review document URL (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/review-tasks/{task_id}/priority": { "patch": { "description": "Updates review task priority. Requires KYC API key and reviews:write scope.", "operationId": "updateKYCReviewPriority", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/tenantPriorityRequest" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Update review task priority (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/review-tasks/{task_id}/reject": { "post": { "description": "Completes review task as rejected with a canonical reason. Requires KYC API key and reviews:write scope.", "operationId": "rejectKYCReviewTask", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/tenantRejectRequest" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Reject review task (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/review-tasks/{task_id}/request-resubmit": { "post": { "description": "Requests a user resubmit for a step. Requires KYC API key and reviews:write scope.", "operationId": "requestKYCReviewResubmit", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/tenantResubmitRequest" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/Request" } }, "type": "object" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Request resubmit from review (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/review-tasks/{task_id}/resubmits": { "get": { "description": "Returns resubmit requests for a review task. Requires KYC API key and reviews:read scope.", "operationId": "listKYCReviewResubmits", "parameters": [ { "description": "Review task UUID", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/Request" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List review resubmits (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/review-tasks/reject-reasons": { "get": { "description": "Returns canonical rejection reasons. Requires KYC API key and reviews:read scope.", "operationId": "getKYCReviewRejectReasons", "parameters": [ { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/RejectReasonRow" }, "type": "array" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List review reject reasons (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/review-tasks/stats": { "get": { "description": "Returns review queue counters. Requires KYC API key and reviews:read scope.", "operationId": "getKYCReviewStats", "parameters": [ { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/StatsRow" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get review stats (KYC)", "tags": [ "KYC Review" ] } }, "/v1/kyc/verification-links": { "get": { "description": "Returns paginated list of verification links. Requires KYC API key and verification-links:read scope.", "operationId": "listKYCVerificationLinks", "parameters": [ { "description": "Page (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Page size (1-100)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Filter by status (active, consumed, revoked)", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Filter by external user ID", "in": "query", "name": "external_user_id", "schema": { "type": "string" } }, { "description": "Filter by external reference", "in": "query", "name": "external_reference", "schema": { "type": "string" } }, { "description": "Filter by flow UUID", "in": "query", "name": "flow_id", "schema": { "type": "string" } }, { "description": "Sort field (default created_at)", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "Sort order: asc, desc (default desc)", "in": "query", "name": "sort_order", "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification links", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/ListLinksResponse" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (verification-links:read scope required)", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List KYC verification links", "tags": [ "KYC Verification Links" ] }, "post": { "description": "Creates a new verification link (flow_id required). Requires KYC API key and sessions:create scope.", "operationId": "createKYCVerificationLink", "parameters": [ { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/CreateLinkRequest" }, "responses": { "201": { "description": "Created or reused link", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/CreateLinkResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (sessions:create scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "An existing verification is awaiting manual review (session_review_pending)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create KYC verification link", "tags": [ "KYC Verification Links" ] } }, "/v1/kyc/verification-links/{id}": { "get": { "description": "Returns a single verification link by UUID. Requires KYC API key and verification-links:read scope.", "operationId": "getKYCVerificationLink", "parameters": [ { "description": "Link UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification link details", "content": { "*/*": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/VerificationLinkResp" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid ID", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get KYC verification link by ID", "tags": [ "KYC Verification Links" ] } }, "/v1/kyc/verification-links/{id}/qr": { "get": { "description": "Returns PNG QR code image for the verification link URL. Requires KYC API key and verification-links:read scope.", "operationId": "getKYCVerificationLinkQR", "parameters": [ { "description": "Link UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "QR size in pixels (1-1024, default 256)", "in": "query", "name": "size", "schema": { "type": "integer" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PNG image", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get QR code for KYC verification link", "tags": [ "KYC Verification Links" ] } }, "/v1/kyc/verification-links/{id}/revoke": { "post": { "description": "Revokes an active link so it can no longer be used. Requires KYC API key and sessions:create scope.", "operationId": "revokeKYCVerificationLink", "parameters": [ { "description": "Link UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/RevokeReasonBody" }, "responses": { "200": { "description": "Revoked link info", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/RevokeLinkResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Revoke KYC verification link", "tags": [ "KYC Verification Links" ] } }, "/v1/kyc/verification-links/batch": { "post": { "description": "Creates multiple verification links in a single request (max 500). Requires KYC API key and sessions:create scope.", "operationId": "batchCreateKYCVerificationLinks", "parameters": [ { "description": "Unix timestamp (seconds, max 5 min drift)", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/BatchCreateRequest" }, "responses": { "200": { "description": "Created links", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/BatchCreateResponse" } }, "type": "object" } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (sessions:create scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Batch create KYC verification links", "tags": [ "KYC Verification Links" ] } } }, "servers": [ { "url": "/tenant" } ], "components": { "requestBodies": { "tenantRejectRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenantRejectRequest" } } }, "description": "Reject payload", "required": true }, "tenantResubmitRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenantResubmitRequest" } } }, "description": "Resubmit payload", "required": true }, "tenantPriorityRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenantPriorityRequest" } } }, "description": "Priority payload", "required": true }, "tenantReviewDecisionRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenantReviewDecisionRequest" } } }, "description": "Optional comment and optimistic lock timestamp" }, "tenantReviewCommentRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tenantReviewCommentRequest" } } }, "description": "Comment payload", "required": true }, "CreateLinkRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLinkRequest" } } }, "description": "Link options (flow_id required)", "required": true }, "RevokeReasonBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeReasonBody" } } }, "description": "Optional revoke reason" }, "BatchCreateRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateRequest" } } }, "description": "Batch create request", "required": true } }, "securitySchemes": { "ApiKeyAuth": { "description": "HMAC-SHA256 Credential=, Signature=. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.", "in": "header", "name": "Authorization", "type": "apiKey" } }, "schemas": { "AMLContract": { "properties": { "aml_screening_completed": { "type": "boolean" }, "aml_screening_status": { "type": "string" }, "aml_service_unavailable": { "type": "boolean" }, "checks": { "additionalProperties": { "type": "string" }, "description": "Checks maps each canonical list ID to its per-session status.\nValues: \"clear\" | \"hit\" | \"skipped\" | \"unchecked\" | \"unavailable\" |\n\"out_of_scope\". See decision_adapter.go for the full enum + meaning\nof each value.", "type": "object" }, "checks_typed": { "description": "ChecksTyped is the typed, list-normalized equivalent of Checks.", "items": { "$ref": "#/components/schemas/CheckResult" }, "type": "array" }, "compliance": { "allOf": [ { "$ref": "#/components/schemas/ComplianceIndividualSummaries" } ], "description": "Compliance carries the typed individual-lookup summaries the\nKontur Compliance API already produces during the AML 4-fan-out\n(CheckPassport / CheckBankruptcy / CheckRKL). Replaces the Focus\n`checkPassport` / `personBankruptcy` / `pepSearch` / `sanctionedPersons`\ncalls — those endpoints have direct equivalents on the Compliance\nAPI which we already authenticate against, so the redundant\nFocus subscription requirement is gone. The orchestrator copies\nthese into applicant_enrichment.{passport_focus, person_bankruptcy}\nso the admin UI's PassportFocusCard / PersonBankruptcyCard render\nfrom real data instead of Focus 403 placeholders." }, "decision": { "description": "\"approved\" | \"declined\" | \"review\"", "type": "string" }, "effective_list_actions": { "additionalProperties": { "type": "string" }, "description": "EffectiveListActions is the immutable policy used for this attempt.\nDownstream enrichment must not reactivate explicitly skipped lists.", "type": "object" }, "effective_match_policy": { "allOf": [ { "$ref": "#/components/schemas/AMLMatchPolicy" } ], "description": "EffectiveMatchPolicy explains which observed matches this attempt scored.\nA nil policy means the historical attempt did not record these settings." }, "error_code": { "type": "string" }, "error_message": { "type": "string" }, "forced_review_reason": { "description": "Coverage diagnostics explain incomplete screening without exposing vendor\npayloads or arbitrary provider error text.", "type": "string" }, "input_fields_used": { "items": { "type": "string" }, "type": "array" }, "lists_checked": { "items": { "type": "string" }, "type": "array" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "description": "Localized holds bilingual renderings (en, ru, ...) of list names and\nhuman-readable hit descriptions. Keyed by ISO-639-1 lang code.", "type": "object" }, "match_details": { "items": { "additionalProperties": {}, "type": "object" }, "type": "array" }, "match_found": { "type": "boolean" }, "match_severity": { "description": "\"LOW\" | \"MEDIUM\" | \"HIGH\" | \"CRITICAL\"", "type": "string" }, "matched_lists": { "items": { "type": "string" }, "type": "array" }, "matches": { "description": "Matches is the typed, list-normalized equivalent of MatchDetails. Each\nhit carries a canonical list_id (from aml_list_mappings), match\nstrength, confidence, matched fields, person identity, and provenance.", "items": { "$ref": "#/components/schemas/AMLMatchDetail" }, "type": "array" }, "provider": { "description": "AML provider identifier", "type": "string" }, "provider_metadata": { "allOf": [ { "$ref": "#/components/schemas/ProviderMetadata" } ], "description": "ProviderMetadata is the rich integration metadata. Visibility: use\nStripAdminFields(&contract.ProviderMetadata, ViewPublic) before\nserializing to webhook or public surfaces — it nils Raw, RawResponseKey,\nand RequestID." }, "providers_called": { "items": { "type": "string" }, "type": "array" }, "providers_errored": { "items": { "type": "string" }, "type": "array" }, "providers_succeeded": { "items": { "type": "string" }, "type": "array" }, "risk_score": { "description": "0.0–1.0", "type": "number" }, "unchecked_lists": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "AMLHit": { "properties": { "decision": { "type": "string" }, "list_type": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "AMLMatchDetail": { "properties": { "confidence": { "description": "0..1", "type": "number" }, "hit_details": { "$ref": "#/components/schemas/HitDetails" }, "list_category": { "description": "sanctions|pep|adverse_media|watchlist|wanted|bankruptcy|other", "type": "string" }, "list_id": { "description": "OFAC_SDN, PEP_WORLD, RU_ROSFINMON_TERRORISM, ...", "type": "string" }, "list_name": { "description": "English display name", "type": "string" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object" }, "match_fields": { "description": "[\"name\",\"dob\",\"passport\"]", "items": { "type": "string" }, "type": "array" }, "match_strength": { "description": "exact|strong|weak", "type": "string" }, "person": { "$ref": "#/components/schemas/PersonIdentity" }, "provenance": { "$ref": "#/components/schemas/MatchProvenance" } }, "type": "object" }, "AMLMatchPolicy": { "properties": { "match_strength": { "type": "string" }, "match_strength_per_list": { "additionalProperties": { "type": "string" }, "type": "object" }, "min_match_confidence": { "type": "number" } }, "type": "object" }, "Activities": { "properties": { "additional": { "items": { "type": "string" }, "type": "array" }, "main": { "type": "string" } }, "type": "object" }, "ActivityCode": { "properties": { "code": { "type": "string" }, "description": { "description": "English", "type": "string" }, "is_primary": { "type": "boolean" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object" }, "name": { "description": "English readable", "type": "string" }, "system": { "description": "OKVED | NAICS | SIC | NACE", "type": "string" } }, "type": "object" }, "ActivityItem": { "properties": { "id": { "type": "string" }, "message": { "type": "string" }, "metadata": { "additionalProperties": {}, "type": "object" }, "session_id": { "type": "string" }, "timestamp": { "type": "string" }, "type": { "$ref": "#/components/schemas/ActivityType" } }, "type": "object" }, "ActivityType": { "enum": [ "session_created", "session_completed", "review_completed", "flow_updated" ], "type": "string", "x-enum-varnames": [ "ActivitySessionCreated", "ActivitySessionCompleted", "ActivityReviewCompleted", "ActivityFlowUpdated" ] }, "Address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" }, "state": { "type": "string" }, "street": { "type": "string" } }, "type": "object" }, "AddressDetails": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "full_text": { "type": "string" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object" }, "postal_code": { "type": "string" }, "region": { "type": "string" }, "street": { "type": "string" } }, "type": "object" }, "AddressEntry": { "properties": { "address": { "$ref": "#/components/schemas/AddressDetails" }, "type": { "description": "registered | actual | mailing | branch", "type": "string" }, "valid_from": { "type": "string" }, "valid_to": { "type": "string" } }, "type": "object" }, "ApplicantAMLProviderInfo": { "properties": { "forced_review_reason": { "type": "string" }, "providers_called": { "items": { "type": "string" }, "type": "array" }, "providers_errored": { "items": { "type": "string" }, "type": "array" }, "providers_succeeded": { "items": { "type": "string" }, "type": "array" }, "service_unavailable": { "type": "boolean" }, "unchecked_lists": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "ApplicantAMLResponse": { "properties": { "aml": { "$ref": "#/components/schemas/AMLContract" }, "aml_provider_info": { "allOf": [ { "$ref": "#/components/schemas/ApplicantAMLProviderInfo" } ], "description": "ProviderInfo carries AML coverage/audit signals that are not part of the\ntyped AML contract. Public views receive only safe coverage fields; admin\nviews also receive provider names for internal observability." }, "aml_screening_completed": { "type": "boolean" }, "aml_screening_status": { "type": "string" }, "applicant_id": { "type": "string" }, "attempt_number": { "type": "integer" }, "checks": { "additionalProperties": { "type": "string" }, "type": "object" }, "checks_typed": { "description": "ChecksTyped is the typed, list-normalized equivalent of Checks.", "items": { "$ref": "#/components/schemas/CheckResult" }, "type": "array" }, "decision": { "type": "string" }, "error_code": { "type": "string" }, "error_message": { "type": "string" }, "hits": { "items": { "$ref": "#/components/schemas/AMLHit" }, "type": "array" }, "lists_checked": { "items": { "type": "string" }, "type": "array" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "description": "Localized carries bilingual renderings (en, ru, ...) of list names.", "type": "object" }, "match_details": { "description": "freeform vendor match data", "items": { "additionalProperties": {}, "type": "object" }, "type": "array" }, "match_severity": { "type": "string" }, "matched_lists": { "items": { "type": "string" }, "type": "array" }, "matches": { "description": "Matches is the typed, list-normalized equivalent of MatchDetails.", "items": { "$ref": "#/components/schemas/AMLMatchDetail" }, "type": "array" }, "provider": { "type": "string" }, "provider_metadata": { "allOf": [ { "$ref": "#/components/schemas/ProviderMetadata" } ], "description": "ProviderMetadata is the rich integration metadata. Provider.Raw /\nRawResponseKey / RequestID are stripped on public surfaces via\nStripAdminFields(&pm, ViewPublic) before serialization." }, "risk_score": { "type": "number" }, "screened_at": { "type": "string" }, "session_id": { "type": "string" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "summary": { "additionalProperties": { "type": "integer" }, "type": "object" }, "verification_id": { "type": "string" } }, "type": "object" }, "ApplicantDetailResponse": { "properties": { "address": { "type": "string" }, "aml_decision": { "type": "string" }, "aml_risk_score": { "type": "number" }, "avatar_photo_url": { "type": "string" }, "avatar_url": { "description": "avatar storage key", "type": "string" }, "client_liveness_score": { "type": "number" }, "created_at": { "type": "string" }, "current_review_decision": { "$ref": "#/components/schemas/CurrentDecision" }, "date_of_birth": { "type": "string" }, "details": { "allOf": [ { "$ref": "#/components/schemas/ApplicantDetails" } ], "description": "Rich OCR-derived aggregate (document metadata, MRZ, barcode, localized\ncountry names). Populated when verification results and/or the applicants\nrow have enrichable data; nil otherwise." }, "doc_liveness_score": { "type": "number" }, "document_back_key": { "type": "string" }, "document_back_url": { "type": "string" }, "document_details": { "$ref": "#/components/schemas/DocumentOCRDetails" }, "document_front_key": { "type": "string" }, "document_front_url": { "type": "string" }, "document_number": { "type": "string" }, "document_photo_key": { "type": "string" }, "document_photo_url": { "description": "Presigned download URLs (time-limited, generated on request).", "type": "string" }, "document_type": { "type": "string" }, "email": { "description": "Contact details from applicant row — previously hidden, now surfaced.", "type": "string" }, "enrichment": { "$ref": "#/components/schemas/EnrichmentWebhookData" }, "enrichment_errors": { "items": { "type": "string" }, "type": "array" }, "expiry_date": { "type": "string" }, "expiry_status": { "description": "ExpiryStatus is the server-computed presentation status for the\ndocument's expiry, accounting for country-specific grace rules\n(RU internal passport, UAE Emirates ID, FR CNI extension, EU 2031,\nUA martial law). Values: \"valid\" | \"expired\" | \"grace\" | \"unknown\".", "type": "string" }, "external_id": { "type": "string" }, "face_match_score": { "type": "number" }, "first_name": { "type": "string" }, "full_name": { "type": "string" }, "full_name_latin": { "type": "string" }, "full_name_native": { "type": "string" }, "full_name_original": { "type": "string" }, "id": { "type": "string" }, "identity_projection": { "$ref": "#/components/schemas/CollectionIdentityProjection" }, "issuing_country": { "type": "string" }, "issuing_state_code": { "type": "string" }, "last_name": { "type": "string" }, "last_session_id": { "description": "Verification data from latest completed session", "type": "string" }, "last_verified_at": { "type": "string" }, "latest_flow_name": { "type": "string" }, "liveness_mode": { "type": "string" }, "liveness_score": { "type": "number" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "description": "Top-level localized bundle — convenience pointer to Details.Localized so\nthat consumers can read `applicant.localized.ru.nationality_name` without\ndescending into `applicant.details.localized.*`.", "type": "object" }, "middle_name": { "type": "string" }, "name_source": { "additionalProperties": {}, "type": "object" }, "nationality": { "type": "string" }, "personal_info": { "$ref": "#/components/schemas/PersonalInfo" }, "phone": { "type": "string" }, "photo_url_expires_at": { "type": "string" }, "portrait_photo_key": { "type": "string" }, "portrait_photo_url": { "type": "string" }, "risk_score": { "type": "number" }, "risk_signals": { "additionalProperties": {}, "description": "Session-level signals — copied from FlowSession on completion.", "type": "object" }, "selfie_photo_key": { "type": "string" }, "selfie_photo_url": { "type": "string" }, "session_summary": { "allOf": [ { "$ref": "#/components/schemas/ApplicantSessionSummary" } ], "description": "SessionSummary aggregates verification-session counts for this applicant by\nterminal verdict. Tenant API list responses omit this field." }, "sessions": { "items": { "$ref": "#/components/schemas/ApplicantSessionResponse" }, "type": "array" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" }, "verification_score": { "type": "integer" }, "verification_status": { "$ref": "#/components/schemas/VerificationStatus" } }, "type": "object" }, "ApplicantDetails": { "properties": { "address": { "$ref": "#/components/schemas/AddressDetails" }, "barcode": { "$ref": "#/components/schemas/BarcodeData" }, "document": { "$ref": "#/components/schemas/DocumentDetails" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object" }, "mrz": { "$ref": "#/components/schemas/MRZData" }, "personal": { "$ref": "#/components/schemas/PersonalDetails" }, "provider": { "$ref": "#/components/schemas/ProviderMetadata" } }, "type": "object" }, "ApplicantDocumentPublicResponse": { "properties": { "attempt_number": { "description": "AttemptNumber is the step attempt that produced the document; IsCurrent\nmarks the latest attempt. Older attempts are history, never merged.", "type": "integer" }, "collection": { "$ref": "#/components/schemas/DocumentExtraction" }, "created_at": { "type": "string" }, "extracted_data": { "$ref": "#/components/schemas/DocumentExtractedData" }, "id": { "type": "string" }, "is_current": { "type": "boolean" }, "issuing_country": { "type": "string" }, "pages": { "items": { "$ref": "#/components/schemas/DocumentPage" }, "type": "array" }, "reason_codes": { "items": { "type": "string" }, "type": "array" }, "session_id": { "type": "string" }, "side": { "description": "\"original\" | \"front\" | \"back\"", "type": "string" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "type": { "type": "string" }, "verification": { "$ref": "#/components/schemas/DocumentVerificationSummary" } }, "type": "object" }, "ApplicantHistoryEntry": { "properties": { "changed_by": { "type": "string" }, "details": { "additionalProperties": {}, "description": "freeform event-specific metadata", "type": "object" }, "previous_status": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string" }, "timestamp": { "type": "string" } }, "type": "object" }, "ApplicantResponse": { "properties": { "address": { "type": "string" }, "aml_decision": { "type": "string" }, "aml_risk_score": { "type": "number" }, "avatar_photo_url": { "type": "string" }, "avatar_url": { "description": "avatar storage key", "type": "string" }, "client_liveness_score": { "type": "number" }, "created_at": { "type": "string" }, "current_review_decision": { "$ref": "#/components/schemas/CurrentDecision" }, "date_of_birth": { "type": "string" }, "details": { "allOf": [ { "$ref": "#/components/schemas/ApplicantDetails" } ], "description": "Rich OCR-derived aggregate (document metadata, MRZ, barcode, localized\ncountry names). Populated when verification results and/or the applicants\nrow have enrichable data; nil otherwise." }, "doc_liveness_score": { "type": "number" }, "document_back_key": { "type": "string" }, "document_back_url": { "type": "string" }, "document_front_key": { "type": "string" }, "document_front_url": { "type": "string" }, "document_number": { "type": "string" }, "document_photo_key": { "type": "string" }, "document_photo_url": { "description": "Presigned download URLs (time-limited, generated on request).", "type": "string" }, "document_type": { "type": "string" }, "email": { "description": "Contact details from applicant row — previously hidden, now surfaced.", "type": "string" }, "enrichment": { "$ref": "#/components/schemas/EnrichmentWebhookData" }, "enrichment_errors": { "items": { "type": "string" }, "type": "array" }, "expiry_date": { "type": "string" }, "expiry_status": { "description": "ExpiryStatus is the server-computed presentation status for the\ndocument's expiry, accounting for country-specific grace rules\n(RU internal passport, UAE Emirates ID, FR CNI extension, EU 2031,\nUA martial law). Values: \"valid\" | \"expired\" | \"grace\" | \"unknown\".", "type": "string" }, "external_id": { "type": "string" }, "face_match_score": { "type": "number" }, "first_name": { "type": "string" }, "full_name": { "type": "string" }, "full_name_latin": { "type": "string" }, "full_name_native": { "type": "string" }, "full_name_original": { "type": "string" }, "id": { "type": "string" }, "issuing_country": { "type": "string" }, "issuing_state_code": { "type": "string" }, "last_name": { "type": "string" }, "last_session_id": { "description": "Verification data from latest completed session", "type": "string" }, "last_verified_at": { "type": "string" }, "latest_flow_name": { "type": "string" }, "liveness_mode": { "type": "string" }, "liveness_score": { "type": "number" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "description": "Top-level localized bundle — convenience pointer to Details.Localized so\nthat consumers can read `applicant.localized.ru.nationality_name` without\ndescending into `applicant.details.localized.*`.", "type": "object" }, "middle_name": { "type": "string" }, "name_source": { "additionalProperties": {}, "type": "object" }, "nationality": { "type": "string" }, "phone": { "type": "string" }, "photo_url_expires_at": { "type": "string" }, "portrait_photo_key": { "type": "string" }, "portrait_photo_url": { "type": "string" }, "risk_score": { "type": "number" }, "risk_signals": { "additionalProperties": {}, "description": "Session-level signals — copied from FlowSession on completion.", "type": "object" }, "selfie_photo_key": { "type": "string" }, "selfie_photo_url": { "type": "string" }, "session_summary": { "allOf": [ { "$ref": "#/components/schemas/ApplicantSessionSummary" } ], "description": "SessionSummary aggregates verification-session counts for this applicant by\nterminal verdict. Tenant API list responses omit this field." }, "updated_at": { "type": "string" }, "verification_score": { "type": "integer" }, "verification_status": { "$ref": "#/components/schemas/VerificationStatus" } }, "type": "object" }, "ApplicantSessionResponse": { "properties": { "applicant_id": { "type": "string" }, "completed_at": { "type": "string" }, "context": { "additionalProperties": {}, "type": "object" }, "created_at": { "type": "string" }, "current_step_id": { "type": "string" }, "decision_reasons": { "items": { "$ref": "#/components/schemas/SessionDecisionReasonResponse" }, "type": "array" }, "device_info": { "$ref": "#/components/schemas/FlowSessionDeviceInfo" }, "expires_at": { "type": "string" }, "external_id": { "type": "string" }, "fingerprint_visitor_id": { "type": "string" }, "flow_id": { "type": "string" }, "flow_version": { "type": "integer" }, "id": { "type": "string" }, "ip_address": { "type": "string" }, "locale": { "type": "string" }, "risk_signals": { "additionalProperties": {}, "type": "object" }, "started_at": { "type": "string" }, "status": { "$ref": "#/components/schemas/SessionStatus" }, "steps_completed": { "type": "integer" }, "user_agent": { "type": "string" }, "verification_link_id": { "type": "string" }, "verification_result": { "type": "string" }, "verification_score": { "type": "integer" } }, "type": "object" }, "ApplicantSessionSummary": { "properties": { "approved": { "description": "Approved: status=completed AND verification_result=approved.", "type": "integer" }, "in_progress": { "description": "InProgress: status in {pending, in_progress, paused}. Active sessions\nthe applicant has not yet finished.", "type": "integer" }, "rejected": { "description": "Rejected: status in {failed, completed} AND verification_result in\n{rejected, declined}. Both spellings exist because the manual-reject\npath (review/task_service.mapDecisionToStatus) emits 'rejected' while\nthe auto-decline path emits 'declined'.", "type": "integer" }, "review": { "description": "Review: status=completed AND verification_result=review (manual review\npending — operator has not yet decided).", "type": "integer" }, "total": { "description": "Total: count of all KYC flow_sessions for this applicant including\ncancelled / expired ones (those sit outside the four buckets above).", "type": "integer" } }, "type": "object" }, "ApplicantVerificationCheckItem": { "properties": { "aml": { "$ref": "#/components/schemas/AMLContract" }, "attempt_number": { "type": "integer" }, "completed_at": { "type": "string" }, "doc_liveness": { "$ref": "#/components/schemas/DocumentLivenessContract" }, "face_liveness": { "$ref": "#/components/schemas/FaceLivenessContract" }, "face_match": { "$ref": "#/components/schemas/FaceMatchContract" }, "kyb": { "$ref": "#/components/schemas/KYBContract" }, "ocr": { "allOf": [ { "$ref": "#/components/schemas/OCRContract" } ], "description": "Typed contract — exactly one will be set based on type." }, "proof_of_address": { "$ref": "#/components/schemas/ProofOfAddressSummary" }, "rejection_reasons": { "items": { "type": "string" }, "type": "array" }, "score": { "type": "number" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "type": { "type": "string" }, "verification_id": { "type": "string" } }, "type": "object" }, "ApplicantVerificationResponse": { "properties": { "applicant_id": { "type": "string" }, "checks": { "items": { "$ref": "#/components/schemas/ApplicantVerificationCheckItem" }, "type": "array" }, "completed_at": { "type": "string" }, "custom_steps": { "items": { "$ref": "#/components/schemas/CustomStepSummary" }, "type": "array" }, "email": { "type": "string" }, "phone": { "type": "string" }, "risk_score": { "type": "number" }, "session_id": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "AuditLogItemResp": { "properties": { "action": { "type": "string" }, "actor_email": { "type": "string" }, "actor_id": { "type": "string" }, "actor_type": { "type": "string" }, "created_at": { "type": "string" }, "details": { "$ref": "#/components/schemas/Details" }, "id": { "type": "string" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string" }, "tenant_id": { "type": "string" } }, "type": "object" }, "BankruptcySnapshot": { "properties": { "case_number": { "type": "string" }, "court": { "type": "string" }, "is_bankrupt": { "type": "boolean" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object" }, "receiver": { "description": "AU / trustee", "type": "string" }, "stage": { "description": "observation | external_management | bankruptcy_proceedings | settlement | completed", "type": "string" }, "started_at": { "type": "string" } }, "type": "object" }, "BarcodeData": { "properties": { "fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "raw": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "BatchCreateRequest": { "properties": { "defaults": { "properties": { "expires_in": { "type": "integer" }, "flow_id": { "type": "string" }, "locale": { "type": "string" }, "redirect_url": { "type": "string" } }, "type": "object" }, "items": { "items": { "properties": { "external_reference": { "type": "string" }, "external_user_id": { "type": "string" }, "metadata": { "additionalProperties": {}, "type": "object" }, "prefilled": { "additionalProperties": {}, "type": "object" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "BatchCreateResponse": { "properties": { "failed": { "items": { "$ref": "#/components/schemas/BatchCreateResult" }, "type": "array" }, "successful": { "items": { "$ref": "#/components/schemas/BatchCreateResult" }, "type": "array" }, "summary": { "$ref": "#/components/schemas/BatchCreateSummary" } }, "type": "object" }, "BatchCreateResult": { "properties": { "error": { "type": "string" }, "error_code": { "type": "string" }, "existing_session_id": { "type": "string" }, "index": { "type": "integer" }, "link": { "$ref": "#/components/schemas/CreateLinkResponse" } }, "type": "object" }, "BatchCreateSummary": { "properties": { "failed": { "type": "integer" }, "successful": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "Beneficiary": { "properties": { "country": { "description": "ISO 3166-1 alpha-2", "type": "string" }, "name": { "type": "string" }, "pep": { "description": "Politically exposed person", "type": "boolean" }, "share": { "type": "string" }, "type": { "description": "e.g. natural_person, legal_entity", "type": "string" } }, "type": "object" }, "BoundingBox": { "properties": { "x1": { "type": "number" }, "x2": { "type": "number" }, "y1": { "type": "number" }, "y2": { "type": "number" } }, "type": "object" }, "BusinessDocumentURLResponse": { "properties": { "key": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "BusinessGetResponse": { "properties": { "data": { "$ref": "#/components/schemas/BusinessResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "BusinessHistoryItem": { "properties": { "changed_by": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "reason": { "type": "string" }, "status": { "type": "string" }, "timestamp": { "type": "string" } }, "type": "object" }, "BusinessPerson": { "properties": { "addresses": { "items": { "$ref": "#/components/schemas/AddressEntry" }, "type": "array" }, "appointed_at": { "type": "string" }, "date_of_birth": { "type": "string" }, "documents": { "items": { "$ref": "#/components/schemas/DocumentRef" }, "type": "array" }, "first_name": { "type": "string" }, "full_name": { "type": "string" }, "id": { "description": "vendor/internal identifier", "type": "string" }, "is_pep": { "type": "boolean" }, "is_sanctioned": { "type": "boolean" }, "last_name": { "type": "string" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object" }, "middle_name": { "type": "string" }, "nationality": { "description": "ISO alpha-2", "type": "string" }, "ownership_pct": { "description": "for beneficiaries/shareholders", "type": "number" }, "resigned_at": { "type": "string" }, "role": { "description": "ceo|cfo|director|general_director|founder|ubo|authorized_signatory|...", "type": "string" }, "role_raw": { "description": "vendor original string (\"Генеральный директор\")", "type": "string" }, "tax_id": { "type": "string" } }, "type": "object" }, "BusinessResponse": { "properties": { "activities": { "$ref": "#/components/schemas/Activities" }, "activities_evidence_sources": { "items": { "type": "string" }, "type": "array" }, "activities_typed": { "items": { "$ref": "#/components/schemas/ActivityCode" }, "type": "array" }, "activities_unavailable_reason_info": { "type": "string" }, "actual_address": { "type": "string" }, "additional_url": { "type": "string" }, "additional_url_evidence_sources": { "items": { "type": "string" }, "type": "array" }, "additional_url_unavailable_reason_info": { "type": "string" }, "addresses_typed": { "items": { "$ref": "#/components/schemas/AddressEntry" }, "type": "array" }, "adverse_media": { "items": { "$ref": "#/components/schemas/MediaHit" }, "type": "array" }, "ai_analysis": { "$ref": "#/components/schemas/KYBAIAnalysis" }, "ai_confirmation_flag": { "type": "boolean" }, "ai_notes": { "type": "string" }, "ai_sources": { "items": { "type": "string" }, "type": "array" }, "ai_summary": { "type": "string" }, "bankruptcy": { "$ref": "#/components/schemas/BankruptcySnapshot" }, "beneficiaries": { "items": { "$ref": "#/components/schemas/Beneficiary" }, "type": "array" }, "beneficiaries_evidence_sources": { "items": { "type": "string" }, "type": "array" }, "beneficiaries_typed": { "items": { "$ref": "#/components/schemas/BusinessPerson" }, "type": "array" }, "beneficiaries_unavailable_reason_info": { "type": "string" }, "business_document_key": { "type": "string" }, "business_document_url": { "type": "string" }, "business_document_url_expires_at": { "type": "string" }, "company_name": { "type": "string" }, "company_status": { "type": "string" }, "country": { "type": "string" }, "created_at": { "type": "string" }, "current_review_decision": { "$ref": "#/components/schemas/CurrentDecision" }, "decision": { "type": "string" }, "director_evidence_sources": { "items": { "type": "string" }, "type": "array" }, "director_name": { "type": "string" }, "director_title": { "type": "string" }, "director_unavailable_reason_info": { "type": "string" }, "directors": { "items": { "$ref": "#/components/schemas/Director" }, "type": "array" }, "directors_typed": { "description": "Typed KYB result fields for sanctions/PEP hits, structured directors,\nactivity classifications, AI analysis, and localized company data.", "items": { "$ref": "#/components/schemas/BusinessPerson" }, "type": "array" }, "enrichment_errors": { "items": { "type": "string" }, "type": "array" }, "evidence_profile": { "additionalProperties": {}, "type": "object" }, "external_id": { "type": "string" }, "financials": { "$ref": "#/components/schemas/FinancialSnapshot" }, "id": { "type": "string" }, "kyb": { "allOf": [ { "$ref": "#/components/schemas/KYBContract" } ], "description": "KYB is the safe typed latest lookup projection. Raw provider metadata and\nmatch provenance are stripped before this response is serialized." }, "kyb_document_analysis": { "$ref": "#/components/schemas/KYBDocumentAnalysisContract" }, "last_session_id": { "type": "string" }, "last_verified_at": { "type": "string" }, "latest_flow_name": { "type": "string" }, "legal_address": { "type": "string" }, "legal_form": { "type": "string" }, "liquidation_date": { "type": "string" }, "litigation": { "items": { "$ref": "#/components/schemas/LitigationCase" }, "type": "array" }, "main_url": { "type": "string" }, "main_url_evidence_sources": { "items": { "type": "string" }, "type": "array" }, "main_url_unavailable_reason_info": { "type": "string" }, "pep": { "items": { "$ref": "#/components/schemas/AMLMatchDetail" }, "type": "array" }, "profile": { "additionalProperties": {}, "type": "object" }, "registration_date": { "type": "string" }, "registration_number": { "type": "string" }, "rejection_reasons": { "items": { "type": "string" }, "type": "array" }, "risk_factors": { "items": { "$ref": "#/components/schemas/RiskFactor" }, "type": "array" }, "risk_level": { "type": "string" }, "risk_score": { "type": "number" }, "sanctions": { "items": { "$ref": "#/components/schemas/AMLMatchDetail" }, "type": "array" }, "shareholders": { "items": { "$ref": "#/components/schemas/BusinessPerson" }, "type": "array" }, "signatories": { "items": { "$ref": "#/components/schemas/BusinessPerson" }, "type": "array" }, "status_date": { "type": "string" }, "status_evidence_sources": { "description": "Evidence sources & unavailability reasons.", "items": { "type": "string" }, "type": "array" }, "status_info": { "type": "string" }, "tax_number": { "type": "string" }, "updated_at": { "type": "string" }, "verification_status": { "type": "string" } }, "type": "object" }, "BusinessSessionItem": { "properties": { "completed_at": { "type": "string" }, "created_at": { "type": "string" }, "external_id": { "type": "string" }, "id": { "type": "string" }, "scope": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "BusinessSessionsResponse": { "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "sessions": { "items": { "$ref": "#/components/schemas/BusinessSessionItem" }, "type": "array" }, "total": { "type": "integer" } }, "type": "object" }, "BusinessSessionsSuccessResponse": { "properties": { "data": { "$ref": "#/components/schemas/BusinessSessionsResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "ChartDataPoint": { "properties": { "approved": { "type": "integer" }, "date": { "description": "YYYY-MM-DD", "type": "string" }, "pending": { "type": "integer" }, "rejected": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "CheckResult": { "properties": { "checked_at": { "type": "string" }, "hit_count": { "type": "integer" }, "list_id": { "type": "string" }, "list_name": { "type": "string" }, "status": { "description": "clear|hit|skipped|error", "type": "string" } }, "type": "object" }, "CollectionIdentityProjection": { "properties": { "document_type": { "type": "string" }, "field_sources": { "additionalProperties": { "items": { "$ref": "#/components/schemas/EvidenceReference" }, "type": "array" }, "type": "object" }, "ocr": { "$ref": "#/components/schemas/OCRContract" } }, "type": "object" }, "CommentRow": { "properties": { "author_display_name": { "description": "AuthorDisplayName is the author label (admin name or API key name).", "type": "string" }, "author_id": { "type": "string" }, "author_type": { "description": "AuthorType is admin_user | system | superadmin_user | api_key.", "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "task_id": { "type": "string" } }, "type": "object" }, "ComplianceIndividualSummaries": { "properties": { "bankruptcy": { "allOf": [ { "$ref": "#/components/schemas/PersonBankruptcyFocus" } ], "description": "Bankruptcy mirrors PersonBankruptcyFocus — bankruptcy proceedings\nfound via Kontur Compliance /individuals/bankruptcy." }, "passport": { "allOf": [ { "$ref": "#/components/schemas/PassportCheckSummary" } ], "description": "Passport mirrors PassportCheckSummary from enrichment.go — the\napplicant's passport status against МВД invalid-passports registry." }, "rkl": { "allOf": [ { "$ref": "#/components/schemas/RKLSummary" } ], "description": "RKL is the controlled-persons-registry entry. RKL has no Focus\ncounterpart — Compliance is the canonical source." } }, "type": "object" }, "Conflict": { "properties": { "code": { "$ref": "#/components/schemas/ConflictCode" }, "field": { "type": "string" }, "left_source": { "$ref": "#/components/schemas/Source" }, "right_source": { "$ref": "#/components/schemas/Source" }, "severity": { "type": "string" } }, "type": "object" }, "ConflictCode": { "enum": [ "name_mismatch", "mrz_validation_mismatch", "document_number_mismatch", "date_of_birth_mismatch", "expiry_date_mismatch", "nationality_mismatch" ], "type": "string", "x-enum-varnames": [ "ConflictNameMismatch", "ConflictMRZValidationMismatch", "ConflictDocumentNumberMismatch", "ConflictDateOfBirthMismatch", "ConflictExpiryDateMismatch", "ConflictNationalityMismatch" ] }, "CreateLinkRequest": { "properties": { "expires_in": { "description": "seconds", "type": "integer" }, "external_reference": { "type": "string" }, "external_user_id": { "type": "string" }, "flow_id": { "type": "string" }, "locale": { "type": "string" }, "metadata": { "additionalProperties": {}, "type": "object" }, "prefilled": { "additionalProperties": {}, "type": "object" }, "redirect_url": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_source": { "type": "string" } }, "type": "object" }, "CreateLinkResponse": { "properties": { "created_at": { "type": "string" }, "delivery_eligible": { "type": "boolean" }, "expires_at": { "type": "string" }, "external_reference": { "type": "string" }, "external_user_id": { "type": "string" }, "flow_id": { "type": "string" }, "id": { "type": "string" }, "link_url": { "type": "string" }, "locale": { "type": "string" }, "qr_code_url": { "type": "string" }, "redirect_url": { "type": "string" }, "reuse_reason": { "$ref": "#/components/schemas/ReuseReason" }, "reused": { "type": "boolean" }, "session_id": { "type": "string" }, "session_resumable": { "type": "boolean" }, "session_status": { "type": "string" }, "short_url": { "type": "string" }, "status": { "type": "string" }, "url": { "type": "string" }, "verification_link": { "type": "string" }, "verification_url": { "type": "string" } }, "type": "object" }, "CurrentDecision": { "properties": { "client_message": { "type": "string" }, "created_at": { "type": "string" }, "decision": { "type": "string" }, "id": { "type": "string" }, "reason_codes": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" }, "session_id": { "type": "string" }, "step_id": { "type": "string" } }, "type": "object" }, "CustomStepConfigSummary": { "properties": { "fields": { "items": { "$ref": "#/components/schemas/CustomStepFieldConfigSummary" }, "type": "array" }, "lists": { "items": { "$ref": "#/components/schemas/CustomStepListConfigSummary" }, "type": "array" }, "mode": { "type": "string" } }, "type": "object" }, "CustomStepDecision": { "properties": { "action": { "type": "string" }, "code": { "type": "string" }, "list_id": { "type": "string" }, "list_label": { "type": "string" }, "match_type": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "CustomStepFieldConfigSummary": { "properties": { "data_type": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "max_length": { "type": "integer" }, "min_length": { "type": "integer" }, "required": { "type": "boolean" }, "validation_preset": { "type": "string" } }, "type": "object" }, "CustomStepFieldSummary": { "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "CustomStepListConfigSummary": { "properties": { "black_list_items_count": { "type": "integer" }, "display": { "type": "string" }, "grey_list_items_count": { "type": "integer" }, "id": { "type": "string" }, "label": { "type": "string" }, "multiple": { "type": "boolean" }, "required": { "type": "boolean" }, "selected_value_ids": { "items": { "type": "string" }, "type": "array" }, "value_policy": { "type": "string" }, "values_count": { "type": "integer" } }, "type": "object" }, "CustomStepListSummary": { "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "values": { "items": { "$ref": "#/components/schemas/CustomStepListValueSummary" }, "type": "array" } }, "type": "object" }, "CustomStepListValueSummary": { "properties": { "id": { "type": "string" }, "label": { "type": "string" } }, "type": "object" }, "CustomStepSummary": { "properties": { "config": { "$ref": "#/components/schemas/CustomStepConfigSummary" }, "decision": { "$ref": "#/components/schemas/CustomStepDecision" }, "execution_id": { "type": "string" }, "fields": { "items": { "$ref": "#/components/schemas/CustomStepFieldSummary" }, "type": "array" }, "lists": { "items": { "$ref": "#/components/schemas/CustomStepListSummary" }, "type": "array" }, "step_id": { "type": "string" }, "step_key": { "type": "string" }, "step_name": { "type": "string" } }, "type": "object" }, "Decision": { "enum": [ "accept", "accept_review", "retry_required" ], "type": "string", "x-enum-varnames": [ "DecisionAccept", "DecisionAcceptReview", "DecisionRetryRequired" ] }, "DeletionRequest": { "properties": { "created_at": { "type": "string" }, "entity_type": { "$ref": "#/components/schemas/EntityType" }, "id": { "type": "string" }, "object_id": { "type": "string" }, "object_type": { "$ref": "#/components/schemas/ObjectType" }, "reason": { "type": "string" }, "rejection_reason": { "type": "string" }, "requested_at": { "type": "string" }, "requested_by_id": { "type": "string" }, "requested_by_name": { "type": "string" }, "reviewed_at": { "type": "string" }, "reviewed_by_name": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "Details": { "properties": { "changes": { "items": { "type": "string" }, "type": "array" }, "metadata": { "additionalProperties": {}, "type": "object" }, "new_value": { "additionalProperties": {}, "type": "object" }, "old_value": { "additionalProperties": {}, "type": "object" } }, "type": "object" }, "Director": { "properties": { "name": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "DocumentCheckResult": { "properties": { "is_authentic": { "type": "boolean" }, "liveness_score": { "type": "number" }, "portrait_replace_score": { "type": "number" }, "printed_copy_score": { "type": "number" }, "rejection_reasons": { "items": { "type": "string" }, "type": "array" }, "screen_replay_score": { "type": "number" }, "similarity_score": { "type": "number" }, "status": { "description": "\"passed\" | \"failed\" | \"review\" | \"error\"", "type": "string" }, "type": { "description": "\"document_ocr\" | \"document_liveness\"", "type": "string" } }, "type": "object" }, "DocumentDetails": { "properties": { "booklet_number": { "type": "string" }, "class": { "type": "string" }, "issuing_authority": { "type": "string" }, "issuing_place": { "type": "string" }, "issuing_state_code": { "type": "string" }, "mrz_type": { "type": "string" }, "series": { "type": "string" } }, "type": "object" }, "DocumentExtractedData": { "properties": { "date_of_birth": { "type": "string" }, "date_of_issue": { "type": "string" }, "document_number": { "type": "string" }, "document_type": { "type": "string" }, "expiry_date": { "type": "string" }, "extended_data": { "additionalProperties": { "type": "string" }, "type": "object" }, "first_name": { "type": "string" }, "full_name": { "type": "string" }, "full_name_latin": { "type": "string" }, "full_name_native": { "type": "string" }, "full_name_original": { "type": "string" }, "gender": { "type": "string" }, "issuing_country": { "type": "string" }, "last_name": { "type": "string" }, "middle_name": { "type": "string" }, "mrz": { "type": "string" }, "nationality": { "type": "string" }, "ocr": { "$ref": "#/components/schemas/OCRContract" }, "place_of_birth": { "type": "string" } }, "type": "object" }, "DocumentExtraction": { "properties": { "doc_liveness": { "$ref": "#/components/schemas/DocumentLivenessContract" }, "doc_liveness_sides": { "additionalProperties": { "$ref": "#/components/schemas/DocumentLivenessContract" }, "type": "object" }, "document_metadata": { "$ref": "#/components/schemas/DocumentStepMetadata" }, "document_order": { "type": "integer" }, "logical_document_id": { "type": "string" }, "ocr": { "$ref": "#/components/schemas/OCRContract" }, "review_decision": { "$ref": "#/components/schemas/ReviewDecision" }, "revision": { "type": "integer" }, "status": { "type": "string" } }, "type": "object" }, "DocumentLivenessContract": { "properties": { "is_real": { "type": "boolean" }, "portrait_replace": { "type": "number" }, "printed_copy": { "type": "number" }, "result_code": { "type": "string" }, "score": { "type": "number" }, "screen_replay": { "type": "number" }, "status": { "description": "Status values from KBY-AI: \"Ok\" | \"Too close to camera!\" | \"Too close to border!\" |\n\"Document cropped!\" | \"Too small!\" | \"Multiple documents\" | \"Is Colorless!\" |\n\"Document not found!\" | \"Unknown\"", "type": "string" }, "status_error": { "type": "string" }, "thresholds": { "$ref": "#/components/schemas/DocumentLivenessThresholds" } }, "type": "object" }, "DocumentLivenessThresholds": { "properties": { "portrait_replace": { "type": "number" }, "printed_copy": { "type": "number" }, "screen_replay": { "type": "number" } }, "type": "object" }, "DocumentOCRDetails": { "properties": { "additional_fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "address": { "description": "Additional", "type": "string" }, "authority_code": { "type": "string" }, "barcode": { "additionalProperties": { "type": "string" }, "type": "object" }, "booklet_number": { "type": "string" }, "date_of_birth": { "type": "string" }, "date_of_expiry": { "type": "string" }, "date_of_issue": { "description": "Issuance", "type": "string" }, "document_class_code": { "type": "string" }, "document_number": { "description": "Document", "type": "string" }, "document_series": { "type": "string" }, "document_type": { "type": "string" }, "first_name": { "description": "Identity", "type": "string" }, "full_name": { "type": "string" }, "full_name_latin": { "type": "string" }, "full_name_native": { "type": "string" }, "full_name_original": { "type": "string" }, "gender": { "type": "string" }, "issuing_authority_name": { "type": "string" }, "issuing_country": { "type": "string" }, "issuing_state_code": { "type": "string" }, "last_name": { "type": "string" }, "localized_fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "middle_name": { "type": "string" }, "mrz_code": { "description": "MRZ", "type": "string" }, "mrz_data": { "additionalProperties": { "type": "string" }, "type": "object" }, "mrz_type": { "type": "string" }, "nationality": { "type": "string" }, "nationality_name": { "type": "string" }, "ocr": { "$ref": "#/components/schemas/OCRContract" }, "personal_number": { "type": "string" }, "place_of_birth": { "type": "string" }, "place_of_issue": { "type": "string" }, "profession": { "type": "string" }, "tax_number": { "type": "string" } }, "type": "object" }, "DocumentPage": { "properties": { "download_url": { "type": "string" }, "download_url_expires_at": { "type": "string" }, "image_id": { "type": "string" }, "side": { "description": "\"original\" | \"front\" | \"back\"", "type": "string" } }, "type": "object" }, "DocumentRef": { "properties": { "class": { "type": "string" }, "country": { "type": "string" }, "expiration_date": { "type": "string" }, "issue_date": { "type": "string" }, "number": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "DocumentStepMetadata": { "properties": { "back_file_id": { "type": "string" }, "front_file_id": { "type": "string" }, "portrait_file_id": { "type": "string" }, "primary_file_id": { "type": "string" } }, "type": "object" }, "DocumentVerificationSummary": { "properties": { "checks": { "description": "per-check results (OCR, liveness)", "items": { "$ref": "#/components/schemas/DocumentCheckResult" }, "type": "array" }, "status": { "description": "\"verified\", \"failed\", \"review\", \"error\", \"deleted\"", "type": "string" } }, "type": "object" }, "EnrichmentWebhookData": { "properties": { "scope": { "type": "string" }, "summary": { "$ref": "#/components/schemas/EnrichmentWebhookSummary" } }, "type": "object" }, "EnrichmentWebhookSummary": { "properties": { "bankruptcy_confirmed": { "type": "boolean" }, "call_statuses": { "additionalProperties": { "type": "string" }, "type": "object" }, "completed_at": { "type": "string" }, "hard_block_reason": { "type": "string" }, "match_count": { "type": "integer" }, "merged_decision": { "type": "string" }, "merged_risk_score": { "type": "number" }, "observed_at": { "type": "string" }, "passport_invalid": { "type": "boolean" }, "status": { "type": "string" } }, "type": "object" }, "EntityType": { "enum": [ "kyc", "kyb" ], "type": "string", "x-enum-varnames": [ "EntityTypeKYC", "EntityTypeKYB" ] }, "ErrorBody": { "properties": { "code": { "type": "string" }, "details": { "items": { "$ref": "#/components/schemas/ErrorDetail" }, "type": "array" }, "doc_url": { "type": "string" }, "existing_session_id": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "retryable": { "type": "boolean" }, "type": { "type": "string" } }, "type": "object" }, "ErrorDetail": { "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" }, "success": { "type": "boolean" } }, "type": "object" }, "EvidenceReference": { "properties": { "document_id": { "type": "string" }, "revision": { "type": "integer" } }, "type": "object" }, "EvidenceReuse": { "properties": { "execution_id": { "type": "string" }, "reason": { "type": "string" }, "recovery_audit_id": { "type": "string" }, "source_attempt_number": { "type": "integer" }, "source_execution_id": { "type": "string" }, "source_verification_id": { "type": "string" } }, "type": "object" }, "FaceData": { "properties": { "eye_dist": { "description": "distance between eyes in pixels", "type": "number" }, "face_luminance": { "description": "numeric brightness (0–255)", "type": "number" }, "face_occlusion": { "description": "occlusion level [0.0, 1.0]", "type": "number" }, "face_quality": { "description": "Face quality metrics from faces[] array", "type": "number" }, "landmark_68": { "description": "68-point facial landmarks, stored for forensic/ML use", "items": { "$ref": "#/components/schemas/LandmarkPoint" }, "type": "array" }, "left_eye_closed": { "description": "Eye closure probability [0.0, 1.0] — separate per eye", "type": "number" }, "mouth_opened": { "description": "mouth opening level [0.0, 1.0]", "type": "number" }, "pitch": { "type": "number" }, "right_eye_closed": { "type": "number" }, "roll": { "type": "number" }, "state": { "allOf": [ { "$ref": "#/components/schemas/FaceStateContract" } ], "description": "Face quality characteristics (qualitative, from face_state)" }, "x1": { "description": "Bounding box in pixels", "type": "number" }, "x2": { "type": "number" }, "y1": { "type": "number" }, "y2": { "type": "number" }, "yaw": { "description": "Head pose angles in degrees", "type": "number" } }, "type": "object" }, "FaceLivenessContract": { "properties": { "face_warnings": { "items": { "type": "string" }, "type": "array" }, "faces": { "items": { "$ref": "#/components/schemas/FaceData" }, "type": "array" }, "is_live": { "type": "boolean" }, "message": { "type": "string" }, "quality": { "type": "number" }, "quality_warning_reason": { "type": "string" }, "score": { "type": "number" }, "status": { "type": "string" }, "threshold": { "type": "number" } }, "type": "object" }, "FaceMatchContract": { "properties": { "confidence_level": { "type": "string" }, "face1_index": { "description": "selected face index in selfie image (file1)", "type": "integer" }, "face2_index": { "description": "selected face index in document/portrait image (file2)", "type": "integer" }, "faces1": { "description": "faces from selfie image (file1 in /compare_face)", "items": { "$ref": "#/components/schemas/FaceData" }, "type": "array" }, "faces2": { "description": "faces from document/portrait image (file2 in /compare_face)", "items": { "$ref": "#/components/schemas/FaceData" }, "type": "array" }, "is_match": { "type": "boolean" }, "result_code": { "type": "string" }, "score": { "type": "number" }, "threshold": { "type": "number" } }, "type": "object" }, "FaceStateContract": { "properties": { "eye_closed": { "description": "at least one eye closed", "type": "boolean" }, "has_mouth_open": { "type": "boolean" }, "has_occlusion": { "type": "boolean" }, "is_boundary_face": { "description": "face partially outside frame", "type": "boolean" }, "is_front": { "type": "boolean" }, "is_not_front": { "type": "boolean" }, "is_small": { "description": "face too small to analyze", "type": "boolean" }, "luminance": { "description": "\"Dark\" | \"Normal\" | \"Light\"", "type": "string" }, "quality": { "description": "String enums — KBY-AI returns strings, NOT ints (old code was wrong)", "type": "string" }, "result": { "description": "\"Real\" | \"Spoof\" | \"No face\" | \"Multiple face\"", "type": "string" } }, "type": "object" }, "FinancialSnapshot": { "properties": { "assets": { "type": "number" }, "authorized_capital": { "type": "number" }, "currency": { "type": "string" }, "employee_count": { "type": "integer" }, "employee_date": { "type": "string" }, "equity": { "type": "number" }, "fiscal_year": { "type": "integer" }, "liabilities": { "type": "number" }, "net_profit": { "type": "number" }, "report_source": { "description": "\"rosstat\", \"vendor\", \"self_declared\"", "type": "string" }, "revenue": { "type": "number" } }, "type": "object" }, "FlowSessionDeviceInfo": { "properties": { "browser_name": { "description": "Structured data from FP Pro VerificationResult (set after device_init).", "type": "string" }, "browser_version": { "type": "string" }, "country_code": { "description": "CountryCode is the ISO 3166-1 alpha-2 country inferred from the user's IP via Fingerprint Pro.\nPrivacy-sensitive: treated as geolocation data under GDPR/local data protection law.", "type": "string" }, "device_type": { "type": "string" }, "fingerprint_request_id": { "type": "string" }, "fp_collection_failed": { "description": "FPCollectionFailed is true when FP Pro was unavailable during device_init\n(CDN blocked in RU without VPN, SDK timeout, ad-blocker, or explicit client signal).\nBy default the fingerprint step continues and records this flag. If the\nstep config sets review_on_unavailable=true, the step routes to needs_review.", "type": "boolean" }, "os": { "type": "string" }, "os_version": { "type": "string" }, "timezone": { "description": "Timezone is the IANA timezone identifier inferred from the user's device/IP via Fingerprint Pro.\nPrivacy-sensitive: treated as geolocation data under GDPR/local data protection law.", "type": "string" }, "user_agent": { "description": "UserAgent now stores a formatted string from FP Pro (e.g. \"Chrome 120 / macOS 14.1\")\ninstead of the raw HTTP User-Agent header.", "type": "string" } }, "type": "object" }, "FunnelStep": { "properties": { "count": { "type": "integer" }, "dropoff": { "type": "number" }, "label": { "type": "string" }, "percentage": { "type": "number" }, "step": { "type": "integer" } }, "type": "object" }, "HitAdditionalInfo": { "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "HitDetails": { "properties": { "additional_information": { "description": "AdditionalInformation is a label/value list with narrative context\nthe source publisher attaches alongside the formal sanction record.", "items": { "$ref": "#/components/schemas/HitAdditionalInfo" }, "type": "array" }, "additional_sanctions": { "description": "AdditionalSanctions enumerate parallel sanctions imposed on the same\nentity from related programs (cross-reference IDs from the vendor).", "items": { "type": "string" }, "type": "array" }, "country": { "description": "ISO 3166-1 alpha-2", "type": "string" }, "crypto_wallets": { "description": "CryptoWallets carries blockchain addresses (e.g. OFAC SDN crypto IDs).\nStored as strings so on-chain monitoring downstream can normalise per\nchain without coupling this contract to a chain-detection lib.", "items": { "type": "string" }, "type": "array" }, "delisted_at": { "type": "string" }, "description": { "description": "Vendor narrative — kept on the typed projection so admin UI doesn't\nhave to dive into MatchProvenance.RawRecord (admin-only) just to\nsurface a short description of the sanction.", "type": "string" }, "education": { "description": "Education enumerates academic / professional credentials the vendor\nattaches to PEP records. Useful context for KYC officers reviewing\nPEP matches — distinguishes a sanctioned junior from a senior\nofficial with the same name.", "items": { "type": "string" }, "type": "array" }, "email_addresses": { "description": "Contact channels of the sanctioned entity. Useful for downstream\npayment-rail / counterparty screening — admin can cross-reference.", "items": { "type": "string" }, "type": "array" }, "last_updated": { "type": "string" }, "listed_at": { "type": "string" }, "notes": { "type": "string" }, "phone_numbers": { "items": { "type": "string" }, "type": "array" }, "position": { "description": "for PEP: \"Minister of Defence\" — promoted from PersonDetails.Title or Positions[0]", "type": "string" }, "programs": { "description": "[\"SDN\", \"SDGT\"]", "items": { "type": "string" }, "type": "array" }, "remarks": { "type": "string" }, "risk_categories": { "description": "vendor categories: OFAC [\"sanction\",\"pep\",\"debarment\",\"ban\"], future shapes vary by source", "items": { "type": "string" }, "type": "array" }, "source_links": { "description": "SourceLinks are URLs to the official sanctioning authority record(s).\nDistinct from the singular SourceURL above (which is a single primary\nlink); SourceLinks may include multiple references per match.\n\nInvariant for OFAC-sourced matches (see ofac_provider.hitDetailsFromNormalized):\nwhen SourceLinks is non-empty, SourceURL == SourceLinks[0]. The duplication\nis deliberate — SourceURL exists for callers that want a single\n\"open record\" link without scanning an array, while SourceLinks\npreserves the full vendor list for callers that surface every\nreference. Do not drop one assuming the other replaces it.", "items": { "type": "string" }, "type": "array" }, "source_url": { "type": "string" }, "websites": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "KYBAIAnalysis": { "properties": { "confidence": { "description": "0..1", "type": "number" }, "confirmation_flag": { "type": "boolean" }, "green_flags": { "items": { "type": "string" }, "type": "array" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object" }, "model_version": { "type": "string" }, "red_flags": { "items": { "type": "string" }, "type": "array" }, "summary": { "description": "English", "type": "string" } }, "type": "object" }, "KYBAcquisitionAction": { "properties": { "action": { "type": "string" }, "detail": { "type": "string" }, "identifiers": { "items": { "type": "string" }, "type": "array" }, "label": { "type": "string" }, "provider": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "KYBActivity": { "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "is_primary": { "type": "boolean" } }, "type": "object" }, "KYBBeneficiary": { "properties": { "is_director": { "type": "boolean" }, "name": { "type": "string" }, "ownership": { "type": "number" } }, "type": "object" }, "KYBContract": { "properties": { "activities": { "description": "Registered business activities", "items": { "$ref": "#/components/schemas/KYBActivity" }, "type": "array" }, "activities_evidence_sources": { "items": { "type": "string" }, "type": "array" }, "activities_typed": { "description": "ActivitiesTyped is the typed replacement for Activities — each entry\ncarries a classification system (OKVED, NACE, NAICS) plus localized\ndescriptions.", "items": { "$ref": "#/components/schemas/ActivityCode" }, "type": "array" }, "activities_unavailable_reason_info": { "type": "string" }, "actual_address": { "type": "string" }, "additional_url": { "type": "string" }, "additional_url_evidence_sources": { "items": { "type": "string" }, "type": "array" }, "additional_url_unavailable_reason_info": { "type": "string" }, "addresses_typed": { "description": "AddressesTyped is the typed, multi-typed replacement for\nLegalAddress/ActualAddress. Each entry is tagged registered | actual |\nmailing | branch.", "items": { "$ref": "#/components/schemas/AddressEntry" }, "type": "array" }, "adverse_media": { "items": { "$ref": "#/components/schemas/MediaHit" }, "type": "array" }, "ai_analysis": { "allOf": [ { "$ref": "#/components/schemas/KYBAIAnalysis" } ], "description": "AIAnalysis includes confidence, red/green flags, and per-language summaries." }, "bankruptcy": { "allOf": [ { "$ref": "#/components/schemas/BankruptcySnapshot" } ], "description": "Bankruptcy captures the company's bankruptcy status when applicable." }, "beneficiaries": { "description": "Ownership structure", "items": { "$ref": "#/components/schemas/KYBBeneficiary" }, "type": "array" }, "beneficiaries_evidence_sources": { "items": { "type": "string" }, "type": "array" }, "beneficiaries_typed": { "description": "BeneficiariesTyped is the typed replacement for Beneficiaries. Each\nBusinessPerson carries role/ownership_pct/localized names.", "items": { "$ref": "#/components/schemas/BusinessPerson" }, "type": "array" }, "beneficiaries_unavailable_reason_info": { "type": "string" }, "company_code": { "description": "Request echo — always present", "type": "string" }, "company_name": { "description": "Company identifiers", "type": "string" }, "confirmation_flag": { "description": "AI assessment", "type": "boolean" }, "confirmation_tier": { "description": "ConfirmationTier is the honest evidence quality of ConfirmationFlag:\nofficial | secondary | ai_synthesis | unconfirmed. Secondary/AI tiers\nmay set ConfirmationFlag=true when the entity was found, without\nimplying official-registry auto-approval strength.", "type": "string" }, "consulted_sources": { "items": { "type": "string" }, "type": "array" }, "country": { "type": "string" }, "decision": { "description": "Decision is the normalized decision derived from ConfirmationFlag +\nrisk score. Values: approved | declined | review.", "type": "string" }, "decision_reason": { "type": "string" }, "director_evidence_sources": { "items": { "type": "string" }, "type": "array" }, "director_name": { "description": "Primary management contact", "type": "string" }, "director_title": { "type": "string" }, "director_unavailable_reason_info": { "description": "Unavailability explanations", "type": "string" }, "directors_typed": { "description": "DirectorsTyped lists directors with structured personal and role data.", "items": { "$ref": "#/components/schemas/BusinessPerson" }, "type": "array" }, "field_evidence": { "description": "Reconciliation evidence is populated by the KYB worker after registry,\ndocument, and declared fields are compared. Admin/review surfaces use it\nto explain why a session was approved, rejected, or sent to review.", "items": { "$ref": "#/components/schemas/KYBFieldEvidence" }, "type": "array" }, "financials": { "allOf": [ { "$ref": "#/components/schemas/FinancialSnapshot" } ], "description": "Financials is the most recent fiscal snapshot (revenue, employees,\nauthorized capital). Nil when vendor does not provide it." }, "incorporation_country": { "description": "ISO 3166-1 alpha-2", "type": "string" }, "incorporation_date": { "description": "IncorporationDate is the parsed date (if the vendor returned RegistrationDate\nin a recognizable format). IncorporationCountry mirrors Country as ISO alpha-2\nfor downstream consumers that want explicit geo separation from registration.", "type": "string" }, "legal_address": { "description": "Primary addresses", "type": "string" }, "legal_form": { "description": "LegalForm is the normalized entity form (LLC, JSC, LTD, ...). LegalFormRaw\npreserves the original vendor string (e.g. \"ООО\" or \"ТОО\" in Russian).", "type": "string" }, "legal_form_raw": { "type": "string" }, "lei": { "description": "LEI is the Legal Entity Identifier (ISO 17442), 20-char alphanumeric.", "type": "string" }, "liquidation_date": { "type": "string" }, "litigation": { "description": "Litigation lists ongoing / historical court cases where the company\nis a party.", "items": { "$ref": "#/components/schemas/LitigationCase" }, "type": "array" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "description": "Localized is the bilingual bundle keyed by ISO-639-1 lang code. Typical\ncontents: company_name, legal_form, country_name, addresses[].", "type": "object" }, "lookup_coverage_tier": { "type": "string" }, "lookup_next_actions": { "items": { "$ref": "#/components/schemas/KYBAcquisitionAction" }, "type": "array" }, "lookup_outcome": { "allOf": [ { "$ref": "#/components/schemas/KYBLookupOutcome" } ], "description": "Lookup provenance and acquisition coverage. These are typed provider\noutcomes, not an unbounded JSON map; raw provider responses remain\nexcluded from public projections." }, "lookup_outcome_reason": { "type": "string" }, "main_url": { "type": "string" }, "main_url_evidence_sources": { "items": { "type": "string" }, "type": "array" }, "main_url_unavailable_reason_info": { "type": "string" }, "notes": { "type": "string" }, "pep": { "items": { "$ref": "#/components/schemas/AMLMatchDetail" }, "type": "array" }, "provider_metadata": { "allOf": [ { "$ref": "#/components/schemas/ProviderMetadata" } ], "description": "ProviderMetadata carries integration metadata. Visibility: strip via\nStripAdminFields(&pm, ViewPublic) before public serialization." }, "provider_statuses": { "items": { "$ref": "#/components/schemas/KYBProviderStatus" }, "type": "array" }, "reconciliation_decision": { "type": "string" }, "reconciliation_reason_codes": { "items": { "type": "string" }, "type": "array" }, "registration_date": { "type": "string" }, "registration_number": { "type": "string" }, "registry_facts": { "items": { "$ref": "#/components/schemas/KYBRegistryFact" }, "type": "array" }, "risk_factors": { "items": { "$ref": "#/components/schemas/RiskFactor" }, "type": "array" }, "risk_level": { "description": "low|medium|high|critical", "type": "string" }, "risk_score": { "description": "Scoring", "type": "number" }, "sanctions": { "description": "Sanctions, PEP, AdverseMedia are screening results applied to the\ncompany entity itself. Each entry includes matched-party and source details.", "items": { "$ref": "#/components/schemas/AMLMatchDetail" }, "type": "array" }, "shareholders": { "description": "Shareholders is populated when the KYB vendor distinguishes UBO from\nshareholders (most providers do not — then this stays empty).", "items": { "$ref": "#/components/schemas/BusinessPerson" }, "type": "array" }, "signatories": { "description": "Signatories are authorized representatives who can act on behalf of\nthe business (not necessarily directors).", "items": { "$ref": "#/components/schemas/BusinessPerson" }, "type": "array" }, "sources": { "description": "Data provenance", "items": { "type": "string" }, "type": "array" }, "status": { "description": "Status", "type": "string" }, "status_date": { "type": "string" }, "status_evidence_sources": { "items": { "type": "string" }, "type": "array" }, "status_info": { "type": "string" }, "summary": { "type": "string" }, "suspicious_signals": { "items": { "type": "string" }, "type": "array" }, "tax_number": { "type": "string" }, "trading_name": { "description": "TradingName is the DBA / commercial name when it differs from the legal\nCompanyName. Optional; KYB AI populates only when the provider returned\na distinct trading name.", "type": "string" } }, "type": "object" }, "KYBDocumentAnalysisContract": { "properties": { "confidence": { "type": "number" }, "decision": { "type": "string" }, "extracted_business_fields": { "$ref": "#/components/schemas/KYBExtractedBusinessFields" }, "files": { "items": { "$ref": "#/components/schemas/KYBDocumentFile" }, "type": "array" }, "fraud_signals": { "items": { "$ref": "#/components/schemas/KYBFraudSignal" }, "type": "array" }, "reasons": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "KYBDocumentFile": { "properties": { "document_group": { "type": "string" }, "document_type": { "type": "string" }, "encrypted": { "type": "boolean" }, "freshness_status": { "type": "string" }, "issue_date": { "type": "string" }, "name": { "type": "string" }, "ocr_required": { "type": "boolean" }, "size_bytes": { "type": "integer" }, "text_bytes": { "type": "integer" }, "type": { "type": "string" } }, "type": "object" }, "KYBExtractedBusinessFields": { "properties": { "actual_address": { "type": "string" }, "company_name": { "type": "string" }, "company_status": { "type": "string" }, "director_name": { "type": "string" }, "director_title": { "type": "string" }, "identifiers": { "items": { "type": "string" }, "type": "array" }, "legal_address": { "type": "string" }, "matched": { "items": { "type": "string" }, "type": "array" }, "missing": { "items": { "type": "string" }, "type": "array" }, "registration_date": { "type": "string" }, "registration_number": { "type": "string" }, "status_date": { "type": "string" }, "status_info": { "type": "string" }, "tax_number": { "type": "string" } }, "type": "object" }, "KYBFieldEvidence": { "properties": { "confidence": { "type": "number" }, "declared_value": { "type": "string" }, "document_source": { "type": "string" }, "document_value": { "type": "string" }, "field": { "type": "string" }, "match_status": { "type": "string" }, "provider": { "type": "string" }, "provider_value": { "type": "string" }, "reason_code": { "type": "string" }, "severity": { "type": "string" } }, "type": "object" }, "KYBFraudSignal": { "properties": { "file": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "KYBLookupOutcome": { "properties": { "auto_approval_eligible": { "type": "boolean" }, "coverage_tier": { "type": "string" }, "decision_bias": { "type": "string" }, "next_actions": { "items": { "$ref": "#/components/schemas/KYBAcquisitionAction" }, "type": "array" }, "official_source_count": { "type": "integer" }, "provider_statuses": { "items": { "$ref": "#/components/schemas/KYBLookupProviderStatus" }, "type": "array" }, "reason": { "type": "string" }, "registry_authority_hint": { "items": { "type": "string" }, "type": "array" }, "requires_manual_review": { "type": "boolean" }, "secondary_source_count": { "type": "integer" } }, "type": "object" }, "KYBLookupProviderStatus": { "properties": { "detail": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "KYBProviderStatus": { "properties": { "detail": { "type": "string" }, "provider": { "type": "string" }, "retrieved_at": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "KYBRegistryFact": { "properties": { "company_name": { "type": "string" }, "confidence": { "type": "number" }, "country": { "type": "string" }, "director_names": { "items": { "type": "string" }, "type": "array" }, "incorporation_date": { "type": "string" }, "legal_address": { "type": "string" }, "lei": { "type": "string" }, "provider": { "type": "string" }, "registration_number": { "type": "string" }, "source_retrieved_at": { "type": "string" }, "source_url": { "type": "string" }, "status": { "type": "string" }, "tax_number": { "type": "string" }, "website": { "type": "string" } }, "type": "object" }, "LandmarkPoint": { "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "type": "object" }, "ListBusinessesResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BusinessResponse" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean" } }, "type": "object" }, "ListLinksPagination": { "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "ListLinksResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/VerificationLinkResp" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/ListLinksPagination" } }, "type": "object" }, "ListResponse": { "properties": { "data": {}, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean" } }, "type": "object" }, "LitigationCase": { "properties": { "amount": { "type": "number" }, "case_number": { "type": "string" }, "closed_at": { "type": "string" }, "court": { "type": "string" }, "currency": { "type": "string" }, "filed_at": { "type": "string" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object" }, "role": { "description": "plaintiff | defendant | third_party", "type": "string" }, "status": { "type": "string" }, "subject": { "type": "string" } }, "type": "object" }, "MRZCheck": { "properties": { "expected": { "type": "string" }, "observed": { "type": "string" }, "valid": { "type": "boolean" } }, "type": "object" }, "MRZData": { "properties": { "document_code": { "type": "string" }, "fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "issuing_state": { "type": "string" }, "raw": { "type": "string" } }, "type": "object" }, "MRZEvidence": { "properties": { "decision_source": { "type": "string" }, "independent_available": { "type": "boolean" }, "independent_valid": { "type": "boolean" }, "parsed": { "$ref": "#/components/schemas/MRZResult" }, "provider_state": { "$ref": "#/components/schemas/ProviderMRZState" }, "provider_validation": { "type": "string" }, "shadow_decision_applied": { "type": "boolean" }, "shadow_state": { "$ref": "#/components/schemas/ShadowMRZState" } }, "type": "object" }, "MRZLayout": { "enum": [ "TD1", "TD2", "TD3" ], "type": "string", "x-enum-varnames": [ "LayoutTD1", "LayoutTD2", "LayoutTD3" ] }, "MRZResult": { "properties": { "checks": { "additionalProperties": { "$ref": "#/components/schemas/MRZCheck" }, "type": "object" }, "date_of_birth": { "type": "string" }, "document_number": { "type": "string" }, "expiry_date": { "type": "string" }, "given_names": { "type": "string" }, "layout": { "$ref": "#/components/schemas/MRZLayout" }, "nationality": { "type": "string" }, "raw_lines": { "items": { "type": "string" }, "type": "array" }, "sex": { "type": "string" }, "surname": { "type": "string" }, "valid": { "type": "boolean" }, "validation_complete": { "type": "boolean" } }, "type": "object" }, "MatchProvenance": { "properties": { "raw_record": { "additionalProperties": {}, "description": "view=Admin only", "type": "object" }, "vendor_list_id": { "type": "string" }, "vendor_match_id": { "type": "string" }, "vendor_source_id": { "description": "VendorSourceID is the source-internal identifier the vendor attaches\nto the sanction record (OFAC v4: Sanction.sourceId — distinct from\nSanction.id which becomes VendorMatchID). Compliance officers cross-\nreference this when looking up the same record in the publishing\nauthority's own database (Treasury OFAC, EU FSF, UK OFSI).", "type": "string" } }, "type": "object" }, "MediaHit": { "properties": { "categories": { "items": { "type": "string" }, "type": "array" }, "language": { "description": "ISO 639-1", "type": "string" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object" }, "published_at": { "type": "string" }, "severity": { "description": "low | medium | high", "type": "string" }, "source": { "description": "publisher domain", "type": "string" }, "summary": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "MediaURLResponse": { "properties": { "created_at": { "type": "string" }, "download_url": { "type": "string" }, "download_url_expires_at": { "type": "string" }, "id": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "type": { "type": "string" } }, "type": "object" }, "NameEvidence": { "properties": { "confidence": { "type": "number" }, "full_name": { "description": "FullName preserves an unstructured name without inventing surname boundaries.", "type": "string" }, "given_names": { "type": "string" }, "language": { "type": "string" }, "script": { "type": "string" }, "source": { "$ref": "#/components/schemas/Source" }, "surname": { "type": "string" } }, "type": "object" }, "OCRContract": { "properties": { "additional": { "additionalProperties": { "type": "string" }, "type": "object" }, "address": { "type": "string" }, "barcode": { "additionalProperties": { "type": "string" }, "description": "Structured secondary data", "type": "object" }, "booklet_number": { "type": "string" }, "date_of_birth": { "description": "Biographic", "type": "string" }, "document_class": { "type": "string" }, "document_name": { "type": "string" }, "document_number": { "description": "Identifiers", "type": "string" }, "document_series": { "type": "string" }, "document_type": { "description": "Document metadata. `document_type` is a normalized document category;\n`document_name` is a human-readable document name when available.", "type": "string" }, "expiry_date": { "description": "FIXED: was losing data due to field name mismatch in parser", "type": "string" }, "field_issues": { "additionalProperties": { "type": "string" }, "description": "FieldIssues explains unavailable normalized fields without exposing provider raw values.", "type": "object" }, "first_name": { "type": "string" }, "full_name": { "description": "Name", "type": "string" }, "gender": { "type": "string" }, "issue_date": { "description": "Document dates", "type": "string" }, "issuing_authority": { "description": "Authority Code (e.g. \"190-013\")", "type": "string" }, "issuing_authority_name": { "description": "Authority full name (e.g. \"MVD PO RESPUBLIKE KHAKASIIA\")", "type": "string" }, "issuing_country": { "description": "Geographic", "type": "string" }, "issuing_place": { "type": "string" }, "issuing_state_code": { "description": "Canonical ISO alpha-3 code; provider originals remain in raw evidence", "type": "string" }, "last_name": { "type": "string" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "description": "key: language (\"Russian\", \"Arabic (Egypt)\")", "type": "object" }, "middle_name": { "type": "string" }, "mrz_code": { "description": "MRZ", "type": "string" }, "mrz_data": { "additionalProperties": { "type": "string" }, "description": "MRZ decoded fields (from KBY-AI \"MRZ\" dict)", "type": "object" }, "mrz_type": { "type": "string" }, "nationality": { "description": "ISO code (e.g. \"RUS\")", "type": "string" }, "nationality_name": { "description": "Full text (e.g. \"Russian Federation\")", "type": "string" }, "native_full_name": { "description": "NativeFullName is one non-Latin display name selected from reconciled\nevidence. It avoids concatenating every localized provider field.", "type": "string" }, "personal_number": { "description": "e.g. Egyptian national ID \"30403011404733\"", "type": "string" }, "place_of_birth": { "type": "string" }, "portrait": { "description": "base64 portrait crop", "type": "string" }, "portrait_position": { "allOf": [ { "$ref": "#/components/schemas/BoundingBox" } ], "description": "face crop bounding box in document" }, "position": { "allOf": [ { "$ref": "#/components/schemas/BoundingBox" } ], "description": "Geometry on the photo image" }, "profession": { "description": "e.g. \"STUDENT\"", "type": "string" }, "reconciliation": { "allOf": [ { "$ref": "#/components/schemas/Reconciliation" } ], "description": "Reconciliation preserves source provenance and the server-side canonical\nchoice. It is optional for backward compatibility with historical OCR rows." }, "tax_number": { "description": "Tax identification number", "type": "string" } }, "type": "object" }, "OCREditHistoryItem": { "properties": { "action": { "type": "string" }, "actor_id": { "type": "string" }, "actor_name": { "type": "string" }, "actor_type": { "type": "string" }, "created_at": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "id": { "type": "string" } }, "type": "object" }, "ObjectType": { "enum": [ "session", "applicant", "kyb_business", "verification" ], "type": "string", "x-enum-varnames": [ "ObjectTypeSession", "ObjectTypeApplicant", "ObjectTypeKYBBusiness", "ObjectTypeVerification" ] }, "PagedListResponse": { "properties": { "data": {}, "pagination": { "$ref": "#/components/schemas/PagedPagination" }, "success": { "type": "boolean" } }, "type": "object" }, "PagedPagination": { "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total_items": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "Pagination": { "properties": { "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "next_cursor": { "type": "string" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "PassportCheckSummary": { "properties": { "invalid_since": { "type": "string" }, "is_invalid": { "type": "boolean" }, "passport_number": { "type": "string" } }, "type": "object" }, "PersonBankruptcyFocus": { "properties": { "address": { "type": "string" }, "bankrupt_date": { "type": "string" }, "matched_inn": { "description": "MatchedINN helps downstream consumers verify we bankruptcy-checked the\napplicant in question — not a homonymous namesake.", "type": "string" }, "snils": { "type": "string" }, "stage": { "description": "\"Наблюдение\"|\"Реализация имущества\"|...", "type": "string" }, "stage_date": { "type": "string" } }, "type": "object" }, "PersonIdentity": { "properties": { "aliases": { "items": { "type": "string" }, "type": "array" }, "birth_place": { "description": "first non-empty from vendor birthPlaces", "type": "string" }, "citizenship": { "description": "distinct from Nationality (naturalised, stateless)", "type": "string" }, "date_of_birth": { "type": "string" }, "documents": { "items": { "$ref": "#/components/schemas/DocumentRef" }, "type": "array" }, "first_name": { "type": "string" }, "full_name": { "type": "string" }, "gender": { "type": "string" }, "last_name": { "type": "string" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object" }, "middle_name": { "type": "string" }, "nationality": { "description": "ISO 3166-1 alpha-2 or alpha-3", "type": "string" } }, "type": "object" }, "PersonalDetails": { "properties": { "additional_fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "nationality_name": { "type": "string" }, "personal_number": { "type": "string" }, "profession": { "type": "string" }, "tax_number": { "type": "string" } }, "type": "object" }, "PersonalInfo": { "properties": { "address": { "$ref": "#/components/schemas/Address" }, "date_of_birth": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "gender": { "type": "string" }, "last_name": { "type": "string" }, "middle_name": { "type": "string" }, "nationality": { "type": "string" }, "ocr_full_name_latin": { "type": "string" }, "ocr_full_name_native": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" }, "ProofOfAddressComponentSummary": { "properties": { "evidence_present": { "type": "boolean" }, "expected_value": { "type": "string" }, "field": { "type": "string" }, "matched": { "type": "boolean" }, "matched_token": { "type": "string" }, "normalized_expected": { "type": "string" }, "normalized_observed": { "type": "string" }, "observed_confidence": { "type": "number" }, "observed_source": { "type": "string" }, "observed_value": { "type": "string" }, "required": { "type": "boolean" }, "weight": { "type": "number" } }, "type": "object" }, "ProofOfAddressSummary": { "properties": { "address_apartment_present": { "type": "boolean" }, "address_building_present": { "type": "boolean" }, "address_city": { "type": "string" }, "address_country": { "type": "string" }, "address_display": { "type": "string" }, "address_line1_present": { "type": "boolean" }, "address_line2_present": { "type": "boolean" }, "address_postal_code": { "type": "string" }, "address_source": { "type": "string" }, "address_street_present": { "type": "boolean" }, "address_subdivision": { "type": "string" }, "applicant_message_code": { "type": "string" }, "blocked_keyword_count": { "type": "integer" }, "config_source": { "type": "string" }, "config_version": { "type": "integer" }, "decision": { "type": "string" }, "document_address_geocode_components": { "items": { "$ref": "#/components/schemas/ProofOfAddressComponentSummary" }, "type": "array" }, "document_address_geocode_confidence_bucket": { "type": "string" }, "document_address_geocode_distance_bucket": { "type": "string" }, "document_address_geocode_expected_display": { "type": "string" }, "document_address_geocode_observed_display": { "type": "string" }, "document_address_geocode_score_bucket": { "type": "string" }, "document_address_geocode_status": { "type": "string" }, "document_address_match_components": { "items": { "$ref": "#/components/schemas/ProofOfAddressComponentSummary" }, "type": "array" }, "document_address_match_score_bucket": { "type": "string" }, "document_address_match_status": { "type": "string" }, "document_address_matched": { "type": "boolean" }, "document_available": { "type": "boolean" }, "document_category": { "type": "string" }, "document_classification_accepted": { "type": "boolean" }, "document_classification_category": { "type": "string" }, "document_classification_confidence_bucket": { "type": "string" }, "document_classification_negative_signals": { "type": "string" }, "document_classification_positive_signals": { "type": "string" }, "document_classification_status": { "type": "string" }, "document_classification_subtype": { "type": "string" }, "document_country": { "type": "string" }, "document_language": { "type": "string" }, "document_ocr_confidence_bucket": { "type": "string" }, "document_ocr_degraded": { "type": "boolean" }, "document_ocr_extracted_bytes": { "type": "integer" }, "document_ocr_text_snippet": { "type": "string" }, "document_ocr_text_truncated": { "type": "boolean" }, "document_page_count": { "type": "integer" }, "document_screenshot": { "type": "boolean" }, "document_subtype": { "type": "string" }, "document_unsupported_reason": { "type": "string" }, "fingerprint_state": { "type": "string" }, "gps_accuracy_meters": { "type": "number" }, "gps_address_distance_bucket": { "type": "string" }, "gps_address_distance_meters": { "type": "number" }, "gps_address_match_radius_meters": { "type": "number" }, "gps_address_mismatch_radius_meters": { "type": "number" }, "gps_address_proximity_status": { "type": "string" }, "gps_country": { "type": "string" }, "gps_geocode_confidence_bucket": { "type": "string" }, "gps_signal_status": { "type": "string" }, "ip_accuracy_radius_bucket": { "type": "string" }, "ip_connection_type": { "type": "string" }, "ip_country": { "type": "string" }, "ip_country_confidence_bucket": { "type": "string" }, "ip_expected": { "type": "string" }, "ip_signal_status": { "type": "string" }, "reason_codes": { "items": { "type": "string" }, "type": "array" }, "reviewer_summary": { "type": "string" }, "route": { "type": "string" } }, "type": "object" }, "ProviderMRZState": { "enum": [ "valid", "invalid", "unavailable", "contract_unknown" ], "type": "string", "x-enum-varnames": [ "ProviderMRZValid", "ProviderMRZInvalid", "ProviderMRZUnavailable", "ProviderMRZContractUnknown" ] }, "ProviderMetadata": { "properties": { "duration_ms": { "type": "integer" }, "evidence_reuse": { "$ref": "#/components/schemas/EvidenceReuse" }, "name": { "type": "string" }, "raw": { "additionalProperties": {}, "type": "object" }, "raw_response_key": { "type": "string" }, "received_at": { "type": "string" }, "request_id": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "QueueItem": { "properties": { "applicant_first_name": { "type": "string" }, "applicant_full_name": { "type": "string" }, "applicant_full_name_latin": { "type": "string" }, "applicant_full_name_native": { "type": "string" }, "applicant_full_name_original": { "type": "string" }, "applicant_id": { "type": "string" }, "applicant_last_name": { "type": "string" }, "applicant_middle_name": { "type": "string" }, "applicant_nationality": { "type": "string" }, "assigned_at": { "type": "string" }, "assigned_display_name": { "description": "AssignedDisplayName is the human-readable assignee label (admin name or API key name).", "type": "string" }, "assigned_to": { "type": "string" }, "assigned_to_type": { "description": "AssignedToType is admin_user | superadmin_user | api_key when assigned.", "type": "string" }, "business_company_name": { "type": "string" }, "business_country": { "type": "string" }, "business_external_id": { "type": "string" }, "business_id": { "type": "string" }, "business_registration_number": { "type": "string" }, "business_tax_number": { "type": "string" }, "created_at": { "type": "string" }, "external_user_id": { "type": "string" }, "flow_id": { "type": "string" }, "flow_name": { "type": "string" }, "id": { "type": "string" }, "priority": { "type": "integer" }, "reason": { "type": "string" }, "review_reasons": { "items": { "type": "object" }, "type": "array" }, "reviewer_email": { "type": "string" }, "reviewer_first_name": { "type": "string" }, "reviewer_last_name": { "type": "string" }, "session_created_at": { "type": "string" }, "session_environment": { "type": "string" }, "session_id": { "type": "string" }, "sla_breached": { "type": "boolean" }, "sla_deadline": { "type": "string" }, "started_at": { "type": "string" }, "status": { "type": "string" }, "system_decision": { "type": "string" }, "tenant_id": { "type": "string" }, "verification_result": { "type": "string" }, "verification_score": { "type": "integer" } }, "type": "object" }, "RKLSummary": { "properties": { "document_number": { "type": "string" }, "in_registry": { "type": "boolean" } }, "type": "object" }, "RealtimeStats": { "properties": { "active_sessions": { "type": "integer" }, "average_time_last_hour": { "description": "seconds", "type": "number" }, "completed_last_hour": { "type": "integer" }, "error_rate_last_hour": { "description": "0-1", "type": "number" }, "failed_last_hour": { "type": "integer" }, "pending_review": { "type": "integer" }, "sessions_last_hour": { "type": "integer" } }, "type": "object" }, "RecommendedAction": { "enum": [ "continue", "continue_review", "recapture" ], "type": "string", "x-enum-varnames": [ "ActionContinue", "ActionReview", "ActionRecapture" ] }, "Reconciliation": { "properties": { "canonical_name": { "$ref": "#/components/schemas/NameEvidence" }, "confidence": { "type": "number" }, "conflicts": { "items": { "$ref": "#/components/schemas/Conflict" }, "type": "array" }, "decision": { "$ref": "#/components/schemas/Decision" }, "evidence_sufficient": { "type": "boolean" }, "fixable_by_recapture": { "type": "boolean" }, "model": { "type": "string" }, "mrz": { "$ref": "#/components/schemas/MRZEvidence" }, "names": { "items": { "$ref": "#/components/schemas/NameEvidence" }, "type": "array" }, "recommended_action": { "$ref": "#/components/schemas/RecommendedAction" } }, "type": "object" }, "RejectReasonRow": { "properties": { "category": { "type": "string" }, "code": { "type": "string" }, "label_en": { "type": "string" }, "label_ru": { "type": "string" } }, "type": "object" }, "Request": { "properties": { "clientMessage": { "type": "string" }, "createdAt": { "type": "string" }, "deliveredAt": { "type": "string" }, "deliveryChannel": { "type": "string" }, "expiresAt": { "type": "string" }, "fulfilledAt": { "type": "string" }, "id": { "type": "string" }, "internalNotes": { "type": "string" }, "reasonCode": { "type": "string" }, "requestedBy": { "type": "string" }, "requestedByDisplayName": { "type": "string" }, "requestedByType": { "type": "string" }, "scope": { "type": "string" }, "sessionID": { "type": "string" }, "status": { "type": "string" }, "stepID": { "type": "string" }, "taskID": { "type": "string" }, "tenantID": { "type": "string" }, "updatedAt": { "type": "string" } }, "type": "object" }, "ReuseReason": { "enum": [ "external_reference", "active_session", "create_race" ], "type": "string", "x-enum-varnames": [ "ReuseReasonExternalReference", "ReuseReasonActiveSession", "ReuseReasonCreateRace" ] }, "ReviewCommentRow": { "properties": { "author_display_name": { "description": "AuthorDisplayName is the author label (admin name or API key name).", "type": "string" }, "author_id": { "type": "string" }, "author_type": { "description": "AuthorType is admin_user | system | superadmin_user | api_key.", "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "task_id": { "type": "string" } }, "type": "object" }, "ReviewDecision": { "properties": { "automatic_status": { "type": "string" }, "decided_at": { "type": "string" }, "decision": { "type": "string" }, "source": { "type": "string" } }, "type": "object" }, "ReviewTaskDetailRow": { "properties": { "applicant_id": { "type": "string" }, "approval_blocked_reason": { "type": "string" }, "assigned_at": { "type": "string" }, "assigned_display_name": { "description": "AssignedDisplayName is the assignee label (admin name or API key name).", "type": "string" }, "assigned_to": { "type": "string" }, "assigned_to_type": { "description": "AssignedToType is admin_user | superadmin_user | api_key when assigned.", "type": "string" }, "completed_at": { "type": "string" }, "created_at": { "type": "string" }, "decision": { "type": "string" }, "decision_at": { "type": "string" }, "decision_by": { "type": "string" }, "decision_by_type": { "description": "DecisionByType is admin_user | superadmin_user | api_key when decided.", "type": "string" }, "decision_display_name": { "description": "DecisionDisplayName is the decider label (admin name or API key name).", "type": "string" }, "external_user_id": { "type": "string" }, "flow_id": { "type": "string" }, "flow_name": { "type": "string" }, "history": { "items": { "$ref": "#/components/schemas/OCREditHistoryItem" }, "type": "array" }, "id": { "type": "string" }, "notes": { "type": "string" }, "priority": { "type": "integer" }, "reason": { "type": "string" }, "reason_details": { "type": "string" }, "reject_reason_code": { "type": "string" }, "resubmit_limit_override": { "description": "ResubmitLimitOverride is a review-task-specific operational exception.\nZero retains the standard per-session cap.", "type": "integer" }, "review_reasons": { "items": { "type": "object" }, "type": "array" }, "session_created_at": { "type": "string" }, "session_entity_type": { "type": "string" }, "session_environment": { "type": "string" }, "session_id": { "type": "string" }, "session_status": { "description": "SessionStatus mirrors flow_sessions.status and is required by\nRequestResubmit to reject terminal sessions early (see\nresubmit.ErrSessionNotActive).", "type": "string" }, "status": { "type": "string" }, "system_decision": { "type": "string" }, "tenant_id": { "type": "string" } }, "type": "object" }, "RevokeLinkResponse": { "properties": { "id": { "type": "string" }, "revoked_at": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "RevokeReasonBody": { "properties": { "reason": { "type": "string" } }, "type": "object" }, "RiskFactor": { "properties": { "category": { "description": "sanctions | pep | adverse_media | structural | financial | operational", "type": "string" }, "code": { "description": "SANCTIONS_HIT | PEP_BENEFICIARY | RECENT_INCORPORATION | NO_FINANCIALS | ...", "type": "string" }, "description": { "type": "string" }, "localized": { "additionalProperties": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "object" }, "severity": { "description": "low | medium | high | critical", "type": "string" }, "weight": { "type": "number" } }, "type": "object" }, "SessionDecisionActorResponse": { "properties": { "display_name": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "role": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "SessionDecisionReasonResponse": { "properties": { "actor": { "$ref": "#/components/schemas/SessionDecisionActorResponse" }, "category": { "type": "string" }, "code": { "type": "string" }, "created_at": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "id": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "source": { "type": "string" }, "step_execution_id": { "type": "string" }, "superseded_at": { "type": "string" }, "superseded_by": { "type": "string" } }, "type": "object" }, "SessionStatus": { "enum": [ "pending", "in_progress", "paused", "completed", "failed", "expired", "cancelled" ], "type": "string", "x-enum-varnames": [ "SessionStatusPending", "SessionStatusInProgress", "SessionStatusPaused", "SessionStatusCompleted", "SessionStatusFailed", "SessionStatusExpired", "SessionStatusCancelled" ] }, "ShadowMRZState": { "enum": [ "valid", "invalid", "unsupported", "unavailable" ], "type": "string", "x-enum-varnames": [ "ShadowMRZValid", "ShadowMRZInvalid", "ShadowMRZUnsupported", "ShadowMRZUnavailable" ] }, "Source": { "enum": [ "mrz", "barcode", "visual_zone", "localized" ], "type": "string", "x-enum-varnames": [ "SourceMRZ", "SourceBarcode", "SourceVisualZone", "SourceLocalized" ] }, "Stats": { "properties": { "approval_rate": { "type": "number" }, "approval_rate_change": { "type": "number" }, "avg_processing_time": { "description": "seconds", "type": "integer" }, "avg_processing_time_change": { "type": "number" }, "completed_verifications": { "type": "integer" }, "completed_verifications_change": { "type": "number" }, "pending_reviews": { "type": "integer" }, "total_sessions": { "type": "integer" }, "total_sessions_change": { "type": "number" } }, "type": "object" }, "StatsRow": { "properties": { "avg_time_minutes": { "type": "integer" }, "completed_today": { "type": "integer" }, "in_progress": { "type": "integer" }, "pending": { "type": "integer" } }, "type": "object" }, "Status": { "enum": [ "pending", "approved", "rejected" ], "type": "string", "x-enum-varnames": [ "StatusPending", "StatusApproved", "StatusRejected" ] }, "SuccessResponse": { "properties": { "data": {}, "success": { "type": "boolean" } }, "type": "object" }, "VerificationLinkResp": { "properties": { "activated_at": { "type": "string" }, "consumed_at": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "expires_at": { "type": "string" }, "external_reference": { "type": "string" }, "external_user_id": { "type": "string" }, "flow_id": { "type": "string" }, "flow_session_id": { "type": "string" }, "id": { "type": "string" }, "locale": { "type": "string" }, "metadata": { "additionalProperties": {}, "type": "object" }, "prefilled_data": { "additionalProperties": {}, "type": "object" }, "redirect_url": { "type": "string" }, "revoked_at": { "type": "string" }, "revoked_reason": { "type": "string" }, "short_code": { "type": "string" }, "status": { "type": "string" }, "token": { "type": "string" }, "updated_at": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_source": { "type": "string" } }, "type": "object" }, "VerificationStatus": { "enum": [ "pending", "verified", "rejected", "review", "expired" ], "type": "string", "x-enum-varnames": [ "VerificationStatusPending", "VerificationStatusVerified", "VerificationStatusRejected", "VerificationStatusReview", "VerificationStatusExpired" ] }, "tenantPriorityRequest": { "properties": { "priority": { "type": "string" } }, "type": "object" }, "tenantRejectRequest": { "properties": { "comment": { "type": "string" }, "if_unmodified_since": { "type": "string" }, "reason_code": { "type": "string" } }, "type": "object" }, "tenantResubmitRequest": { "properties": { "client_message": { "type": "string" }, "internal_notes": { "type": "string" }, "reason_code": { "type": "string" }, "request_id": { "type": "string" }, "scope": { "type": "string" }, "step_id": { "type": "string" } }, "type": "object" }, "tenantReviewCommentRequest": { "properties": { "content": { "description": "Content is the comment text (required, non-empty after trim).", "example": "Document photo is blurry", "type": "string" } }, "type": "object" }, "tenantReviewCommentResponse": { "properties": { "author_display_name": { "type": "string" }, "author_id": { "type": "string" }, "author_type": { "type": "string" }, "comment_id": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string" }, "message": { "type": "string" }, "task_id": { "type": "string" } }, "type": "object" }, "tenantReviewDecisionRequest": { "properties": { "comment": { "type": "string" }, "if_unmodified_since": { "type": "string" } }, "type": "object" }, "tenantReviewTaskResponse": { "properties": { "comments": { "items": { "$ref": "#/components/schemas/ReviewCommentRow" }, "type": "array" }, "task": { "$ref": "#/components/schemas/ReviewTaskDetailRow" } }, "type": "object" } } } }