> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# KYB quickstart: business verification in 10 minutes

> Verify a business end-to-end in under 10 minutes — registry lookup, UBO, officers, AML, and webhooks. Pay-per-call $2.00 KYB, no contracts.

This guide walks you through a complete KYB verification in under 10 minutes. You'll create a workflow, start a session, deliver the hosted verification link to your business contact, wait for the webhook, and fetch the final decision.

## Prerequisites

* A Didit application with KYB enabled. Create one at [business.didit.me](https://business.didit.me) if needed.
* An API key from *Developer Settings → API Keys*.
* A webhook endpoint reachable from the internet (for the decision webhook).

## Steps

<Steps>
  <Step title="Create a KYB workflow in the console">
    Navigate to *Workflows → Create workflow*. Choose **Business Verification** as the workflow type.

    Enable the features you need:

    * **Company registry lookup** (required)
    * **Company AML** (recommended)
    * **Key People** (required for most regulated industries)
    * **Documents** (optional — pick document types you'll require)

    Save and copy the `workflow_id` — you'll use it in the next step.
  </Step>

  <Step title="Create a Business Verification (KYB) session via the API">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "workflow_id": "YOUR_KYB_WORKFLOW_ID",
        "vendor_data": "biz-acme-001"
      }'
    ```

    The response contains the `session_id`, `session_number`, and `url` — the hosted verification link you deliver to the business contact. The workflow's type (KYB) automatically flags the session as a business session.
  </Step>

  <Step title="Send the link to your business contact">
    Deliver the `url` to the company admin via your own email or chat. They open it, fill in the registry data, add key people and UBOs, and upload documents.

    You can customize the hosted experience with branding, logo, and domain — see [White-label](/console/white-label).
  </Step>

  <Step title="Receive the status webhook">
    When the business finishes the flow and KYB processing reaches a terminal status, Didit POSTs a `status.updated` event to your webhook endpoint. Business-session events carry `session_kind: "business"` inside `data` — filter on that to route the event to your KYB handler.

    Verify the `X-Signature-V2` HMAC signature before trusting the event (see [webhooks](/integration/webhooks)), then trigger your downstream logic. Store the destination's `secret_shared_key` (returned when you register the webhook) as `DIDIT_WEBHOOK_SECRET` in your `.env`.

    Example payload:

    ```json theme={null}
    {
      "event": "status.updated",
      "application_id": "app_abc123",
      "timestamp": "2026-04-18T12:30:00Z",
      "data": {
        "session_id": "bs_01H...",
        "session_kind": "business",
        "vendor_data": "biz-acme-001",
        "status": "APPROVED",
        "previous_status": "IN_PROGRESS"
      }
    }
    ```
  </Step>

  <Step title="Retrieve the decision (optional)">
    <Note>
      The `status.updated` webhook payload already contains the full decision. You only need to call this endpoint if you didn't subscribe to webhooks, or you want to fetch the decision on demand later.
    </Note>

    ```bash theme={null}
    curl https://verification.didit.me/v3/session/bs_01H.../decision/ \
      -H "x-api-key: YOUR_API_KEY"
    ```

    The decision includes registry data, key people (UBOs, shareholders, directors and representatives), AML hits, documents, and per-feature results. See [response schema](/business-verification/response-schema) for the full payload reference.
  </Step>

  <Step title="Act on the decision">
    Based on `status`:

    * `APPROVED` — onboard the business.
    * `DECLINED` — reject and log the reason code.
    * `IN_REVIEW` — wait for the analyst decision; you'll receive another webhook when it resolves.
  </Step>
</Steps>

## Node.js example

```typescript theme={null}
import fetch from 'node-fetch';

const API_KEY = process.env.DIDIT_API_KEY!;
const WORKFLOW_ID = process.env.DIDIT_KYB_WORKFLOW_ID!;
const BASE_URL = 'https://verification.didit.me';

async function startKybVerification(vendorData: string) {
  const res = await fetch(`${BASE_URL}/v3/session/`, {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ workflow_id: WORKFLOW_ID, vendor_data: vendorData }),
  });
  if (!res.ok) throw new Error(`Session create failed: ${res.status}`);
  return res.json();
}

async function getDecision(sessionId: string) {
  const res = await fetch(`${BASE_URL}/v3/session/${sessionId}/decision/`, {
    headers: { 'x-api-key': API_KEY },
  });
  return res.json();
}

// Kick off the flow
const { session_id, url } = await startKybVerification('biz-acme-001');
console.log('Deliver this URL to your contact:', url);

// ... later, after the webhook confirms completion:
const decision = await getDecision(session_id);
console.log('KYB status:', decision.status);
```

## What happens automatically

* Company registry lookup against 190+ jurisdictions.
* UBO and officer extraction from registry data.
* Company-level AML screening (sanctions, PEP, adverse media).
* Person-level AML for each identified party.
* Document OCR and cross-referencing.
* [Business profile](/business-verification/business-profiles) creation and aggregation keyed by `vendor_data`.

## Next steps

<CardGroup cols={3}>
  <Card title="Integration guide" icon="book" href="/business-verification/integration-guide">
    End-to-end architecture, polling vs webhooks, retry logic.
  </Card>

  <Card title="KYB webhooks" icon="bolt" href="/business-verification/webhooks">
    Every KYB event and payload shape.
  </Card>

  <Card title="Statuses" icon="list-check" href="/business-verification/statuses">
    Session, feature, and registry status reference.
  </Card>

  <Card title="Response schema" icon="file-lines" href="/business-verification/response-schema">
    The full KYB decision payload.
  </Card>

  <Card title="Business entities" icon="building" href="/entities/businesses/overview">
    How profiles aggregate across sessions.
  </Card>
</CardGroup>