KYB quick start

This section describes the minimum integration scenario: obtaining a KYB API key, creating a verification link for a business, and sending it to the company representative. The representative goes through the KYB flow on the OneKYC page; the result then arrives through a webhook or API.

Step 1. Get a KYB API key

In the API keys section of the admin panel:

1. Click "Create key".

2. Select type: KYB.

3. Select environment: Production or Sandbox.

4. Copy api_key (format kyb_live_...) and api_secret. The secret is shown once — store it in a secure vault.

KYB keys are valid only for /tenant/v1/kyb/* endpoints. KYC keys (kyc_live_*) cannot call the KYB API.

Step 2. Create a verification link

From your server, send a request to the Tenant KYB API (HMAC signing is mandatory — the scheme matches KYC, see Authentication):

POST undefined/v1/kyb/verification-links

Example request (JavaScript / Node.js):

const crypto = require("crypto");
const https = require("https");

const body = JSON.stringify({
  flow_id: "your_kyb_flow_id",
  external_user_id: "company-001",
  expires_in: 259200, // 72 hours in seconds
  locale: "en",
});

const timestamp = Math.floor(Date.now() / 1000).toString();
const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
const stringToSign = `${timestamp}\nPOST\n/tenant/v1/kyb/verification-links\n${bodyHash}`;
const signature = crypto
  .createHmac("sha256", "your_api_secret")
  .update(stringToSign)
  .digest("hex");

// Request headers
const headers = {
  "Content-Type": "application/json",
  "X-Timestamp": timestamp,
  Authorization: `HMAC-SHA256 Credential=kyb_live_your_key, Signature=${signature}`,
};

The response schema (id, url, status, expires_at, etc.) is described in the OpenAPI block above.

Send the url from the response to the company representative (by email, SMS, or as a QR code). Opening the link automatically creates a KYB session.

Step 3. The user completes the KYB flow

The company representative opens the link in a browser and works through the steps:

1. Company data — name, registration number, country of registration.

2. Executive and beneficial owner data — full name, ownership share.

3. Document upload — charter, registration certificate.

4. AI check — automated analysis (typical time — 2–3 minutes; the user sees a waiting screen).

Step 4. Receive the result

Through a webhook (recommended): configure the endpoint under Webhooks in the admin panel. OneKYC sends the kyb.business.verified, kyb.business.rejected, or kyb.business.review_required event.

Through the API: query the result by the external company identifier:

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

The response structure (success, data with company fields) is fully described in the Swagger specification — see the OpenAPI block above or the KYB API reference section.

Next steps

• KYB API reference — full endpoint list with parameters

• KYB webhooks — event types and payload formats

• Authentication — HMAC signature computation procedure