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. Specification: Swagger UI, openapi3.json.

Businesses

List businesses

GET undefined/v1/kyb/businesses

Get a business by ID

GET 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.

GET undefined/v1/kyb/businesses/external/{external_id}

Business verification sessions

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

GET 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.

GET undefined/v1/kyb/businesses/{business_id}/history

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.

DELETE 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.

GET 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.

GET undefined/v1/kyb/businesses/external/{external_id}/document

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.

GET undefined/v1/kyb/applicants/external/{external_id}/documents

Verification links

Create a verification link

POST undefined/v1/kyb/verification-links

Batch create verification links

POST undefined/v1/kyb/verification-links/batch

List verification links

GET undefined/v1/kyb/verification-links

Get a verification link by ID

GET undefined/v1/kyb/verification-links/{id}

Verification link QR code

GET undefined/v1/kyb/verification-links/{id}/qr

Revoke a verification link

POST 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

GET undefined/v1/kyb/metrics/stats

Time series chart

GET undefined/v1/kyb/metrics/chart

Verification funnel

GET undefined/v1/kyb/metrics/funnel

Recent activity feed

GET undefined/v1/kyb/metrics/activity

Active sessions in real time

GET undefined/v1/kyb/metrics/realtime

Data export to CSV

GET undefined/v1/kyb/metrics/export

Audit log

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

GET 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).

List / stats / reject reasons

GET undefined/v1/kyb/review-tasks

GET undefined/v1/kyb/review-tasks/stats

GET undefined/v1/kyb/review-tasks/reject-reasons

Task detail and decisions

GET undefined/v1/kyb/review-tasks/{task_id}

POST undefined/v1/kyb/review-tasks/{task_id}/assign

POST undefined/v1/kyb/review-tasks/{task_id}/approve

POST undefined/v1/kyb/review-tasks/{task_id}/reject

POST 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.

PreviousKYB quick start NextKYB webhooks

Last updated 9 days ago