Verify any business.
Surface every UBO.

# 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)
- Business Verification core (registry + UBO + officers + Key People): $2.00 per check
- Company AML screening:                                                  $0.20 per check
- Each linked KYC session spawned for a UBO / officer:                    $0.33 per KYC bundle
- KYB document collection (per-document OCR + tamper check):              $0.20 per document
- 500 free verifications every month, forever, on every account.

## 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