🏢Business verification (KYB)

What it does

Parallel to personal KYC but for legal entities. The data model captures jurisdiction-specific identifiers (UK Companies House number, US EIN + state, German Handelsregister + court, French SIREN + RCS, etc.), required documents, and beneficial-owner / director chains. Eleven registry providers ship today, covering ~140 jurisdictions; the discrepancy detector compares what the user typed against what the registry returned and flags blockers before submit.

How it works

1. 1

   Pick the country. The form re-renders with only the fields and documents that jurisdiction requires.

2. 2

   Hit Run lookup. The router walks a per-country provider chain (paid first when configured, then country-specialized free providers, then OpenCorporates, then GLEIF) and returns the first hit.

3. 3

   Apply a result with one click. The discrepancy detector then highlights any field-by-field mismatches between what you typed and what the registry returned — blockers in red, warnings in amber.

4. 4

   Upload mandatory documents — certificate of incorporation, articles of association, proof of address, ownership chart — as the country profile demands.

5. 5

   Add beneficial owners (≥25% ownership) and directors. Each gets sanctions-screened individually against OFAC SDN, EU consolidated, UN consolidated, and UK HMT.

6. 6

   Submit. The row flips to status=pending, the sanctions screen runs inline, and operators see hits in the dashboard along with their match score and the registry comparison.

Why it matters

• ✓Eleven providers ship today — seven free (GLEIF, Companies House, SEC EDGAR, INSEE Sirene, BrasilAPI CNPJ, OpenKBO, OpenCorporates) and four paid stubs (Sumsub, Onfido, Trulioo, ComplyAdvantage) that activate when their env vars are set.
• ✓The router prefers paid providers when configured — operators who paid expect their data to win — but silently falls back to free ones so the flow never breaks because a key is missing.
• ✓Discrepancy detection isn't a separate step. The lookup endpoint returns a per-field severity report inline, so the UI can refuse the submit when blocker-level mismatches exist (wrong jurisdiction, wrong LEI, wildly different names).
• ✓Sanctions screening stays in-house — candidate names never leave your infrastructure to a third-party watch-list API.
• ✓UBO tracking is first-class: each natural person is screened separately and ownership percentages are recorded.
• ✓Every verified business gets a partner-facing trust level (unverified / basic / verified / enhanced / qualified) returned via Bearer API at /api/v1/businesses/[id]/trust AND as a claim in the OIDC id_token when the business:trust scope is granted. Admins can override the level with an audited reason for cases the calculator can't judge.

Trigger a registry lookup

Copy-paste starting point for integrating this feature.

# Force GLEIF (Apple's real LEI), attach to an existing BV row to get
# a discrepancy report comparing the registry hit to what the user typed.
curl -X POST https://docsign.example.com/api/business-verification/lookup \
  -H "cookie: docsign_session=..." \
  -H "content-type: application/json" \
  -d '{
    "lei": "HWUPKR0MPOU8FGXBT394",
    "businessId": "cmpqk1...",
    "forceProvider": "gleif"
  }'

# Response includes hits[] + discrepancy.items[] with severity per field:
#   { "field": "legalName", "user": "Wrong Co", "registry": "Apple Inc.",
#     "severity": "blocker", "note": "names do not match" }

Related features