KYB Integration Guide

This guide is the companion to the quickstart. It covers the architecture, every integration decision, and the operational patterns that make KYB reliable in production.

Architecture

Authentication

All requests require the x-api-key header with your application’s API key. See API authentication for key rotation, environment separation, and scopes.

Session creation

Single endpoint: POST /v3/session/. The workflow’s type determines whether the session is KYC or KYB — no explicit “business” flag is needed. Recommended fields on creation:

Field	Purpose
`workflow_id`	Required — references your KYB workflow.
`vendor_data`	Your identifier for the business. Binds the session to a Business entity.
`callback_url`	Optional — where to redirect the user after completion.
`expected_details`	Optional — `{ company_name, registry_country, registration_number }`. Pre-fills the company registry search: the country of incorporation is pre-selected and locked (`registry_country` as `XX`, or `XX-YY` for state-level registries, e.g. `US-CA`), the company-name and registration-number fields are pre-filled, and the asserted search runs automatically — combining both identifiers when both are present. Prefill only — mismatches do not produce warnings.
`metadata`	Optional JSON attached to the session.

Full schema: create session.

Delivering the hosted link

The response url is a hosted verification link. Options for delivery:

Email it from your own platform.
Embed it in your onboarding UI as a link.
Open it in an in-app webview (iOS / Android / React Native).

You can customize the hosted experience — logo, color, domain, email templates — via White-label.

Polling vs webhooks

Webhooks are the recommended pattern. Didit POSTs completion events to your subscribed endpoint as soon as processing finishes. Polling is supported for development or when your webhook endpoint is unreachable:

Poll GET /v3/session/{id}/decision/ with exponential backoff (every 10s initially, up to 60s).
Stop polling when status is one of APPROVED, DECLINED, IN_REVIEW.

Polling at high frequency may hit rate limits. Always prefer webhooks in production.

Webhook handling

Subscribe to the events you care about — the same events cover both KYC and KYB, with session_kind: "business" inside the payload to identify business-session events:

status.updated — session status changed. Filter on data.session_kind === "business" for KYB sessions.
data.updated — session data changed (registry refresh, key-people submission, documents, ongoing AML). Same session_kind filter applies.
business.status.updated / business.data.updated — the linked Business entity changed.

Full event catalog: KYB webhooks. Signature verification and retry semantics: webhooks reference.

Handling decisions

switch (decision.status) {
  case 'APPROVED':
    await onboardBusiness(decision);
    break;
  case 'DECLINED':
    await logRejection(decision.decision_reason_code, decision);
    break;
  case 'IN_REVIEW':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'RESUBMITTED':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}

See KYB statuses for the full state machine and reason codes.

Resubmission flow

When a Business Verification (KYB) session transitions to RESUB_REQUESTED (or a feature is marked for resubmission), the business needs to upload corrected or additional data. You can:

Re-deliver the same url — the hosted flow picks up where resubmission is needed.
Open a case in the Business Console to track the back-and-forth internally.

Business profile aggregation

If you pass vendor_data on session creation, Didit aggregates all sessions for that business into a single Business entity. Use the entity’s features map to answer “is this business fully verified right now?” without iterating sessions. Benefits:

Periodic re-KYB flows append to the same profile.
Transactions monitored against the same vendor_data carry the business’s risk context.
UBOs and officers linked to User entities populate cross-entity relationships.

Best practices

Practice	Why
Always pass `vendor_data`	Without it, the session is orphaned and can’t be aggregated.
Use webhooks, not polling	Lower latency, no rate limit pressure.
Verify webhook signatures	Prevents spoofed events.
Store the `session_id` on your side	Needed to retrieve the decision and generate PDFs.
Tag sessions with `metadata`	Simplifies reporting and debugging.
Set up a test workflow	Use a sandbox workflow for integration testing before production.

Error handling

Scenario	Response
Invalid `workflow_id`	`400 Bad Request`
Duplicate session with same `vendor_data`	Creates a new session — that’s by design, since re-verification is expected.
Dangerous country	Session is created but immediately `DECLINED` with reason `blocked_country`.
Blocklisted `vendor_data`	Session auto-declined with reason `blocked_business`.
Rate limit	`429 Too Many Requests` with `Retry-After` header.

Full rate limiting reference.

Next steps

Webhooks

Every KYB event and payload.

Statuses

State machine reference.

Response schema

Decoding the KYB decision.

Getting Started

Features

Business Profiles

Reference

Console

Architecture

Authentication

Session creation

Delivering the hosted link

Polling vs webhooks

Webhook handling

Handling decisions

Resubmission flow

Business profile aggregation

Best practices

Error handling

Next steps

Webhooks

Statuses

Response schema

​Architecture

​Authentication

​Session creation

​Delivering the hosted link

​Polling vs webhooks

​Webhook handling

​Handling decisions

​Resubmission flow

​Business profile aggregation

​Best practices

​Error handling

​Next steps

Webhooks

Statuses

Response schema

Architecture

Authentication

Session creation

Delivering the hosted link

Polling vs webhooks

Webhook handling

Handling decisions

Resubmission flow

Business profile aggregation

Best practices

Error handling

Next steps