The KYB Session Lifecycle: Statuses & Webhooks

A KYB verification isn't a single yes/no answer — it's a process with moving parts. The registry lookup might approve instantly while document verification waits on a resubmission and entity AML sits in review pending an analyst. To integrate KYB cleanly, you need to know exactly what state every part of a verification is in, and you need your own systems to update the moment any of those states change. That's what the session lifecycle and webhooks are for.

Didit's Business Verification API exposes the full state machine: a status on the overall session, a status on each feature, a separate set of statuses for the business entity once it's under management, and webhooks that fire on every change. The full company verification is $2.00, and this guide maps the entire lifecycle — every status, every webhook, and the management API that ties it together.

Key takeaways

• Three layers of state. A KYB verification has a session status, per-feature statuses, and — once managed — a business-entity status.
• Eight session statuses. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.
• Six feature statuses on each of the four KYB features: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.
• Three entity statuses under management: ACTIVE, FLAGGED, BLOCKED.
• Webhooks on everything. status.updated and data.updated (with session_kind: business) for sessions; business.status.updated and business.data.updated for managed entities.
• A full management API — POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/, PATCH .../update-status/.

What the KYB lifecycle covers

A KYB verification produces state at three layers, and each answers a different question:

• The session answers "how is the verification going overall?"
• Each feature answers "where does the registry / company AML / documents / key people check stand?"
• The business entity answers "what's the operational standing of this company in our system right now?"

You read all three, and you keep them in sync with webhooks rather than polling. A verification starts as a session, resolves its features, lands on an overall outcome, and then — once you start managing the company — carries a business-entity status that you control as circumstances change.

Why it matters

Without granular state, KYB integration degrades into guesswork: a single "pending" flag tells you nothing about which check is holding things up or what action would unblock it. With per-feature statuses, you can route precisely — ask the applicant to resubmit a document, queue an entity-AML match for analyst review, prompt a UBO to finish their KYC — instead of failing the whole verification.

Webhooks matter because KYB is asynchronous. Registry data, document OCR, and screening results arrive at different times, and human review takes longer still. Polling for changes is wasteful and slow; webhooks push the change the moment it happens, so your records reflect reality without a cron job hammering the API.

Technical details

A KYB session is created against the unified /v3/ API and reports its lifecycle state back.

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "your_kyb_workflow_id",
    "vendor_data": "merchant_6601",
    "callback": "https://yourapp.com/kyb/callback"
  }'

A status.updated webhook carries the session status and per-feature statuses:

{
  "event": "status.updated",
  "session_kind": "business",
  "session_id": "kyb_3a90f1c2",
  "vendor_data": "merchant_6601",
  "status": "IN_REVIEW",
  "features": {
    "kyb_registry": "APPROVED",
    "kyb_company_aml": "IN_REVIEW",
    "kyb_documents": "RESUB_REQUESTED",
    "kyb_key_people": "APPROVED"
  }
}

Session statuses. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.

Feature statuses. Each of kyb_registry, kyb_company_aml, kyb_documents, and kyb_key_people reports one of: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.

Webhooks. For sessions: status.updated (lifecycle changes) and data.updated (enriched data), both carrying session_kind: "business". For managed entities: business.status.updated and business.data.updated.

Price. $2.00 per company verification.

Managing the business entity

Once a company is verified, it becomes an entity you manage through the businesses API:

• POST /v3/businesses/create/ — register a business entity.
• GET /v3/businesses/ — list managed businesses.
• GET /v3/businesses/{vendor_data}/ — fetch one business by its vendor_data reference.
• PATCH .../update-status/ — change the entity status.

The entity carries its own status, independent of the verification session: ACTIVE (in good standing), FLAGGED (under review for a risk signal), or BLOCKED (suspended). This is the operational layer — a company can complete an APPROVED session and later be FLAGGED because monitoring surfaced something. Changes to the entity emit business.status.updated and business.data.updated so downstream systems stay current.

The lifecycle, end to end

A typical verification walks the layers in order. The session opens at NOT_STARTED, moves to IN_PROGRESS as features run, and each feature resolves — registry APPROVED, documents perhaps RESUB_REQUESTED until a clean upload arrives, company AML IN_REVIEW until an analyst clears a match, key people APPROVED. When every feature settles, the session lands on APPROVED, DECLINED, or IN_REVIEW. From there the company enters management as an ACTIVE entity, and its status can later move to FLAGGED or BLOCKED as ongoing oversight dictates — each transition pushed to you by webhook.

Use cases

• Marketplaces route sellers precisely: resubmit a document, finish a UBO's KYC, or hold an entity-AML match — without failing the whole onboarding.
• Fintech and banking platforms keep corporate-account records in sync with webhooks instead of polling, and flag or block entities as risk changes.
• Lending providers track each underwriting check's status and update borrower standing through the management API.
• Crypto B2B platforms maintain an auditable lifecycle of every counterparty entity from verification through ongoing standing.

How to integrate with Didit

1. Build the workflow. In the Business Console, create a KYB workflow with the features you need.
2. Create the session. POST /v3/session/ with your KYB workflow_id and a vendor_data reference.
3. Subscribe to webhooks. Handle status.updated and data.updated (session_kind: business) for sessions, and business.status.updated / business.data.updated for managed entities.
4. Manage entities. Use POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/, and PATCH .../update-status/ to keep each company ACTIVE, FLAGGED, or BLOCKED.

Because it's all on the unified /v3/ API, the same lifecycle model carries across KYC, monitoring, and KYB — one consistent state machine for the whole identity-and-fraud platform.

Frequently asked questions

What are the KYB session statuses?

NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, and EXPIRED.

What statuses do individual features report?

Each of kyb_registry, kyb_company_aml, kyb_documents, and kyb_key_people reports NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, or AWAITING_USER.

Which webhooks should I subscribe to?

For sessions, status.updated and data.updated (with session_kind: business). For managed business entities, business.status.updated and business.data.updated.

How do I change a company's standing after verification?

Use the management API — PATCH .../update-status/ — to set the entity to ACTIVE, FLAGGED, or BLOCKED.

What does a KYB verification cost?

$2.00 per company for the full verification — registry, UBO, officers, and entity AML.

Ready to get started?

Read the Business Verification overview in the docs, see how it fits the rest of the platform on the Business Verification product page, and check transparent per-call pricing on the pricing page. When you're ready, start free — 500 free KYC checks every month, and business verification at $2.00 per company.