Create Business
Pre-create a business without a KYB session. All fields are optional, but you should always send vendor_data — without it the record cannot be linked to sessions or transactions. When provided, vendor_data must be unique among non-deleted businesses (exact match; conflicts return 400). Not idempotent.
Overview
Explicitly creates a Business entity before any Business Verification (KYB) session runs.When to use it
- Pre-seed metadata (partner, tier, internal identifiers) before the first Business Verification (KYB) session.
- Migrate from another KYB vendor with an existing business roster.
- Transaction-only registration — submit transactions for a business that you verified through an offline process.
Notes
vendor_datais required and unique per application. Duplicates return a conflict error — usePATCH /v3/businesses/{vendor_data}/to update.- Registry-derived fields (
legal_name,registration_number,country_code) can be seeded but will be overwritten by the first approved Business Verification (KYB) session’s registry data. - If
country_codematches your application’s dangerous countries list, the business is created inBLOCKEDstatus. - Emits
business.data.updated.
Permissions
Role must grantcreate:businesses.
Related
Authorizations
Body
Your unique identifier for this business (free-form string, NOT a UUID). Optional but strongly recommended. When provided, must be unique among non-deleted businesses for the application; matched exactly as sent.
Friendly display name shown in the console (takes precedence over legal_name for UI display).
255Official legal name of the company.
255Company registration or incorporation number.
100Country of incorporation (ISO 3166-1 alpha-2, e.g. GB, US).
10Initial lifecycle status. Defaults to ACTIVE.
ACTIVE, FLAGGED, BLOCKED Arbitrary JSON object you attach to the business. Defaults to {}.
Response
Business created. Full business record returned (same shape as Get Business).
Full business detail. Extends BusinessListItem with metadata and updated_at.
Didit's stable internal UUID for this business.
Your unique identifier for this business (passed when creating sessions). This can be null when no vendor identifier was supplied.
Custom display name set by you
Official legal name from registry or manual entry
Company registration or incorporation number
Country of incorporation (ISO 3166-1 alpha-2, e.g. GB, US).
Best available name: display_name if set, otherwise legal_name
Lifecycle status of the business record (NOT a session status). ACTIVE is the default, FLAGGED marks it for manual attention, BLOCKED prevents new sessions for this vendor_data.
ACTIVE, FLAGGED, BLOCKED Total number of verification sessions for this business
Number of approved sessions
Number of declined sessions
Number of sessions in review
Aggregated per-feature status across all of this business's KYB sessions. Currently the only key is KYB (the registry company check status). Possible values: Approved, Declined, In Review, Not Finished, Resub Requested.
Same data as features, as an ordered array of {feature, status} objects.
Timestamp of the most recent session
Timestamp of the first session
Timestamp of the most recent activity (status change, session update, etc.)
Tags assigned to this business
Custom metadata JSON you attached to this business. Defaults to {}.