Skip to main content
POST
curl

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_data is required and unique per application. Duplicates return a conflict error — use PATCH /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_code matches your application’s dangerous countries list, the business is created in BLOCKED status.
  • Emits business.data.updated.

Permissions

Role must grant create:businesses.

Authorizations

x-api-key
string
header
required

Body

application/json
vendor_data
string | null

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.

display_name
string | null

Friendly display name shown in the console (takes precedence over legal_name for UI display).

Maximum string length: 255

Official legal name of the company.

Maximum string length: 255
registration_number
string | null

Company registration or incorporation number.

Maximum string length: 100
country_code
string | null

Country of incorporation (ISO 3166-1 alpha-2, e.g. GB, US).

Maximum string length: 10
status
enum<string>
default:ACTIVE

Initial lifecycle status. Defaults to ACTIVE.

Available options:
ACTIVE,
FLAGGED,
BLOCKED
metadata
object | null

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_internal_id
string<uuid>

Didit's stable internal UUID for this business.

vendor_data
string | null

Your unique identifier for this business (passed when creating sessions). This can be null when no vendor identifier was supplied.

display_name
string | null

Custom display name set by you

Official legal name from registry or manual entry

registration_number
string | null

Company registration or incorporation number

country_code
string | null

Country of incorporation (ISO 3166-1 alpha-2, e.g. GB, US).

effective_name
string | null

Best available name: display_name if set, otherwise legal_name

status
enum<string>

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.

Available options:
ACTIVE,
FLAGGED,
BLOCKED
session_count
integer

Total number of verification sessions for this business

approved_count
integer

Number of approved sessions

declined_count
integer

Number of declined sessions

in_review_count
integer

Number of sessions in review

features
object

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.

features_list
object[]

Same data as features, as an ordered array of {feature, status} objects.

last_session_at
string<date-time> | null

Timestamp of the most recent session

first_session_at
string<date-time> | null

Timestamp of the first session

last_activity_at
string<date-time> | null

Timestamp of the most recent activity (status change, session update, etc.)

tags
object[]

Tags assigned to this business

created_at
string<date-time>
metadata
object

Custom metadata JSON you attached to this business. Defaults to {}.

updated_at
string<date-time>