# KYB API reference > **API status.** The KYB Tenant API is in beta. Endpoints, data formats, and API versions may change. Track documentation updates. Base URL: `/tenant/v1/kyb/` Authentication: HMAC-SHA256 with a KYB key (`kyb_live_*` or `kyb_test_*`). The signing scheme matches KYC — see [Authentication](/en/api/authentication). Specification: [Swagger UI](https://api.onekyc.io/tenant/docs/), [openapi3.json](https://api.onekyc.io/tenant/docs/openapi3.json). --- ## Businesses [#businesses] ### List businesses [#list-businesses] API operations: - `GET /v1/kyb/businesses` --- ### Get a business by ID [#get-a-business-by-id] API operations: - `GET /v1/kyb/businesses/{business_id}` --- ### Get a business by external ID [#get-a-business-by-external-id] Looks up the business by your system identifier (`external_id`) supplied when the verification link was created. API operations: - `GET /v1/kyb/businesses/external/{external_id}` --- ### Business verification sessions [#business-verification-sessions] Returns the KYB sessions linked to the business (verification attempt history). API operations: - `GET /v1/kyb/businesses/{business_id}/sessions` --- ### Business history [#business-history] Returns the chronological event log for the business (creation, status updates, verification results). Required scope: **businesses:read**. API operations: - `GET /v1/kyb/businesses/{business_id}/history` --- ### Delete business data (GDPR) [#delete-business-data-gdpr] Submits a deletion request for business data, including documents and verification results. Actual deletion requires OneKYC approval; after approval, execution is irreversible. Required scope: **businesses:write**. API operations: - `DELETE /v1/kyb/businesses/{business_id}` --- ## Media files [#media-files] ### Get a media file [#get-a-media-file] Returns a signed download URL for a media file by its identifier (document UUID). Required scope: **kyb.media:read**. API operations: - `GET /v1/kyb/media/{media_id}` ### Download a business document [#download-a-business-document] The `GET /v1/kyb/businesses/{business_id}` response contains: - `business_document_key` — document storage key - `business_document_url` — signed download URL (lifetime is limited) - `business_document_url_expires_at` — URL expiration - `profile` — company profile fields entered during the KYB flow, including `email`, `phone`, `trade_name`, `website`, `business_type`, activity fields, ownership structure, and identifiers To download the business document, send an HTTP GET to the URL from `business_document_url`. No authentication is required to download. > **Note.** Use the dedicated `/businesses/external/{external_id}/document` endpoint to refresh a single download URL, or `/documents` to obtain every current file. Business details and `business_document_url` do not represent a complete file list. ### Download a business document by external ID [#download-a-business-document-by-external-id] Returns a fresh signed URL for the document uploaded during KYB verification by the `external_id` you supplied when creating the verification link. Required scope: **kyb.documents:read**. API operations: - `GET /v1/kyb/businesses/external/{external_id}/document` ### Download all company documents [#download-all-company-documents] Use `GET /tenant/v1/kyb/businesses/external/{external_id}/documents`, or `GET /tenant/v1/kyb/businesses/{business_id}/documents` when you have the OneKYC business ID. Both require a KYB key with **kyb.documents:read**. The key selects production or sandbox; a query parameter cannot switch the environment. The response is `{"success": true, "data": [...]}`. Each item contains `key`, `url`, `session_id`, `step_id` and `expires_at`, with `group` when a document group is recorded. The array includes the active files from every company-document step of the current KYB session. It does not combine older sessions or superseded attempts. Existing multi-file sessions are supported without uploading the files again. An existing business without documents returns an empty array. Signed links are temporary bearer links: keep them private and repeat this request when they expire. An unavailable storage, security check or disclosure audit returns 503 without a partial list of links. A missing business returns 404. The singular `/document` endpoint remains available for compatibility and returns one file. Use `/documents` whenever a step may contain multiple files. Applicant document endpoints return documents of linked people, such as beneficiaries, rather than company files. API operations: - `GET /v1/kyb/businesses/external/{external_id}/documents` API operations: - `GET /v1/kyb/businesses/{business_id}/documents` ### Download KYB-related applicant documents by external ID [#download-kyb-related-applicant-documents-by-external-id] Returns documents uploaded by an applicant inside a KYB flow, for example a beneficiary KYC session. Use the `external_id`/`external_user_id` supplied when creating that verification link, not the verification link UUID. Required scope: **kyb.documents:read**. API operations: - `GET /v1/kyb/applicants/external/{external_id}/documents` --- ## Verification links [#verification-links] ### Create a verification link [#create-a-verification-link] API operations: - `POST /v1/kyb/verification-links` --- ### Batch create verification links [#batch-create-verification-links] API operations: - `POST /v1/kyb/verification-links/batch` --- ### List verification links [#list-verification-links] API operations: - `GET /v1/kyb/verification-links` --- ### Get a verification link by ID [#get-a-verification-link-by-id] API operations: - `GET /v1/kyb/verification-links/{id}` --- ### Verification link QR code [#verification-link-qr-code] API operations: - `GET /v1/kyb/verification-links/{id}/qr` --- ### Revoke a verification link [#revoke-a-verification-link] API operations: - `POST /v1/kyb/verification-links/{id}/revoke` After revocation, the link transitions to the `revoked` status and can no longer be activated. --- ## Metrics [#metrics] Base path: `/tenant/v1/kyb/metrics/`. Requires the `kyb.metrics:read` scope. ### Aggregated statistics [#aggregated-statistics] API operations: - `GET /v1/kyb/metrics/stats` ### Time series chart [#time-series-chart] API operations: - `GET /v1/kyb/metrics/chart` ### Verification funnel [#verification-funnel] API operations: - `GET /v1/kyb/metrics/funnel` ### Recent activity feed [#recent-activity-feed] API operations: - `GET /v1/kyb/metrics/activity` ### Active sessions in real time [#active-sessions-in-real-time] API operations: - `GET /v1/kyb/metrics/realtime` ### Data export to CSV [#data-export-to-csv] API operations: - `GET /v1/kyb/metrics/export` --- ## Audit log [#audit-log] Returns the KYB action log. Requires the `kyb.audit:read` scope. API operations: - `GET /v1/kyb/audit` --- ## Review tasks [#review-tasks] Manual review queue and decisions for KYB sessions. Requires `kyb.reviews:read` / `kyb.reviews:write` (and `kyb.media:read` for document URLs). Full guide: [Review tasks (Tenant API)](/en/api/review). ### List / stats / reject reasons [#list--stats--reject-reasons] API operations: - `GET /v1/kyb/review-tasks` API operations: - `GET /v1/kyb/review-tasks/stats` API operations: - `GET /v1/kyb/review-tasks/reject-reasons` ### Task detail and decisions [#task-detail-and-decisions] API operations: - `GET /v1/kyb/review-tasks/{task_id}` API operations: - `POST /v1/kyb/review-tasks/{task_id}/assign` API operations: - `POST /v1/kyb/review-tasks/{task_id}/approve` API operations: - `POST /v1/kyb/review-tasks/{task_id}/reject` API operations: - `POST /v1/kyb/review-tasks/{task_id}/request-resubmit` --- ## Error codes [#error-codes] | Code | Description | | ----- | ----------------------------------------------------- | | `400` | Bad request (invalid parameters or fields) | | `401` | Authentication error (invalid key or signature) | | `403` | Forbidden (insufficient scopes) | | `404` | Object not found | | `409` | Conflict (for example, duplicate `external_id`) | | `429` | Rate limit exceeded | | `500` | Internal server error | For details on error formats and limits, see [Errors and limits](/en/api/errors-and-limits). ## Complete verification evidence [#complete-verification-evidence] Individual business responses (ID and external ID) include safe typed `kyb` lookup evidence and `kyb_document_analysis` when available. These retain normalized company fields, localized names, lookup/provider coverage, acquisition details, and document analysis beyond the compact `evidence_profile`. Evidence is scoped to the business tenant and its latest session, and filtered by current attempts. Explicit newer attempts suppress older results even before replacement results exist. Historical results without execution metadata use the highest observed attempt. Optional read failures are exposed as `enrichment_errors` (`evidence_results_unavailable` or `evidence_attempts_unavailable`) and omit the derived profile.