> For the complete documentation index, see [llms.txt](https://finext.gitbook.io/one-kyc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://finext.gitbook.io/one-kyc/kyb/api-reference.md).

# 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](/one-kyc/api/authentication.md). Specification: [Swagger UI](https://github.com/ONE-KYC/backend/tree/main/tenant/docs/README.md), [openapi3.json](https://github.com/ONE-KYC/backend/tree/main/tenant/docs/openapi3.json).

***

## Businesses

### List businesses

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/businesses`

***

### Get a business by ID

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/businesses/{business_id}`

***

### Get a business by external ID

Looks up the business by your system identifier (`external_id`) supplied when the verification link was created.

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/businesses/external/{external_id}`

***

### Business verification sessions

Returns the KYB sessions linked to the business (verification attempt history).

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/businesses/{business_id}/sessions`

***

### Business history

Returns the chronological event log for the business (creation, status updates, verification results). Required scope: **businesses:read**.

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/businesses/{business_id}/history`

***

### 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**.

<mark style="color:red;">`DELETE`</mark> `undefined/v1/kyb/businesses/{business_id}`

***

## Media files

### Get a media file

Returns a signed download URL for a media file by its identifier (document UUID). Required scope: **kyb.media:read**.

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/media/{media_id}`

### 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.** If the URL has expired, request the business data again through `GET /v1/kyb/businesses/{business_id}` to obtain a new URL.

### 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**.

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/businesses/external/{external_id}/document`

### 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**.

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/applicants/external/{external_id}/documents`

***

## Verification links

### Create a verification link

<mark style="color:green;">`POST`</mark> `undefined/v1/kyb/verification-links`

***

### Batch create verification links

<mark style="color:green;">`POST`</mark> `undefined/v1/kyb/verification-links/batch`

***

### List verification links

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/verification-links`

***

### Get a verification link by ID

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/verification-links/{id}`

***

### Verification link QR code

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/verification-links/{id}/qr`

***

### Revoke a verification link

<mark style="color:green;">`POST`</mark> `undefined/v1/kyb/verification-links/{id}/revoke`

After revocation, the link transitions to the `revoked` status and can no longer be activated.

***

## Metrics

Base path: `/tenant/v1/kyb/metrics/`. Requires the `kyb.metrics:read` scope.

### Aggregated statistics

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/metrics/stats`

### Time series chart

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/metrics/chart`

### Verification funnel

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/metrics/funnel`

### Recent activity feed

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/metrics/activity`

### Active sessions in real time

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/metrics/realtime`

### Data export to CSV

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/metrics/export`

***

## Audit log

Returns the KYB action log. Requires the `kyb.audit:read` scope.

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/audit`

***

## 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)](/one-kyc/api/review.md).

### List / stats / reject reasons

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/review-tasks`

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/review-tasks/stats`

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/review-tasks/reject-reasons`

### Task detail and decisions

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyb/review-tasks/{task_id}`

<mark style="color:green;">`POST`</mark> `undefined/v1/kyb/review-tasks/{task_id}/assign`

<mark style="color:green;">`POST`</mark> `undefined/v1/kyb/review-tasks/{task_id}/approve`

<mark style="color:green;">`POST`</mark> `undefined/v1/kyb/review-tasks/{task_id}/reject`

<mark style="color:green;">`POST`</mark> `undefined/v1/kyb/review-tasks/{task_id}/request-resubmit`

***

## 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](/one-kyc/api/errors-and-limits.md).