Verify any business.
Understand its ownership.

# Didit Business Verification (KYB) — integrate in 5 minutes

You are integrating Didit's Business Verification (Know Your Business / KYB)
module into <my_stack>. Follow these steps exactly. Every URL, header, and
workflow-type value below is canonical — do not paraphrase or "improve" them.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. Create a KYB workflow
In the Business Console: Workflows -> Create workflow -> select
"Business Verification" as the workflow type. Enable the features you need:

- Company registry lookup       (required)
- Company Anti-Money Laundering (AML)                   (recommended)
- Key People                    (required for most regulated industries)
- Documents                     (optional - configure which document types)

Save and copy the workflow_id. KYB workflows automatically create
business sessions - there is no extra "business" flag to set on the
session create call.

## 3. Create a business session via the API
POST https://verification.didit.me/v3/session/
Headers:
  x-api-key:    <your-api-key>      (lowercase, hyphenated)
  Content-Type: application/json
Body:
  {
    "workflow_id": "<your-kyb-workflow-id>",
    "vendor_data": "biz-acme-001"
  }

Response:
  - session_id          (e.g. bs_01H...)
  - session_number      (sequential)
  - url                 (hosted verification link)

Deliver the url to the business administrator via your own channel.
They open it, confirm registry data, add Ultimate Beneficial Owners
(UBOs) and officers, upload documents, and submit.

## 4. Webhooks
Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
with subscribed_events:
  status.updated, data.updated,
  business.status.updated, business.data.updated

Every delivery carries an X-Signature-V2 header you MUST verify before
trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
  1. sortKeys(payload) recursively
  2. shortenFloats (truncate trailing zeros after the decimal point)
  3. JSON.stringify the result
  4. HMAC-SHA256 with the secret_shared_key
  5. Hex-encode, compare to the X-Signature-V2 header.

Business-session events carry session_kind: "business" inside data and
the business_session_id. Route on session_kind to your KYB handler.

Example status.updated payload:
{
  "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"
  }
}

## 5. Fetch the decision (optional - the webhook already carries it)
GET https://verification.didit.me/v3/session/{session_id}/decision/
Headers:
  x-api-key: <your-api-key>

Top-level shape:
  - status                              "APPROVED" | "DECLINED" | "IN_REVIEW" | "RESUBMITTED" | "IN_PROGRESS" | "NOT_STARTED"
  - session_kind                        "business"
  - registry_checks[]                   per-jurisdiction company registry payloads
  - company_aml_checks[]                entity AML hits (sanctions, PEP, adverse media)
  - key_people_checks[]                 registry-disclosed + user-submitted UBOs / shareholders / directors / representatives, plus ubo_kyc_summary
  - document_verifications[]            uploaded documents with Optical Character Recognition (OCR) fields
  - business_session_id                 mirrors session_id

Each key_people entry includes role tags (ubo, shareholder, director,
representative, authorized_signatory, etc.), ownership_percentage, voting
percentage, and - if Know Your Customer (KYC) is required for that role - a linked_kyc_session_id
pointing at a child User Verification session.

## 6. Hard rules - do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- KYB is workflow-typed - there is no standalone POST /v3/business-verification/.
  Set the workflow type to "Business Verification" in the console; the
  session created against that workflow_id is automatically a business session.
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Session status casing: APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, IN_PROGRESS, NOT_STARTED (uppercase, underscore).
- Always verify webhook signatures before trusting payload data.

## 7. Pricing reference (public)
- Registry retrieval: priced by country and delivered tier. See https://docs.didit.me/getting-started/kyb-registry-pricing for the staging catalog and confirm production rollout. Ownership data is returned only where the source has it.
- Company AML screening:                                                  $0.20 per check
- Each linked KYC session spawned for a UBO / officer:                    $0.33 per KYC bundle
- KYB document collection: USD 0.20 per workflow step in the current staging release, not per upload; production rollout pending.
- The 500 monthly free checks cover eligible core KYC modules, including document capture; not lookup, identity wallets, registry retrieval or KYB documents.

## 8. Verify your integration
- Sandbox starts on signup at https://business.didit.me - no separate flag.
- Test companies (mocked registry responses) available in sandbox mode.
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/business-verification/overview