Skip to main content
POST
/
v3
/
businesses
/
create
curl
curl -X POST 'https://verification.didit.me/v3/businesses/create/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"vendor_data": "company-456", "legal_name": "New Corp Ltd", "country_code": "US"}'
{ "didit_internal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "vendor_data": "company-456", "display_name": null, "legal_name": "New Corp Ltd", "registration_number": null, "country_code": "US", "effective_name": "New Corp Ltd", "status": "ACTIVE", "session_count": 0, "approved_count": 0, "declined_count": 0, "in_review_count": 0, "metadata": {}, "comments": [], "created_at": "2026-03-15T10:30:00Z", "updated_at": "2026-03-15T10:30:00Z" }

​
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
required

Your unique identifier for this business (free-form string, NOT a UUID). Must be unique among non-deleted businesses for the application; matching is case-insensitive after normalisation.

​
display_name
string | null

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

​
legal_name
string | null

Official legal name of the company.

​
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).

​
region
string | null

ISO 3166-2 subdivision code (e.g. CA, NY for US states).

​
status
enum<string>
default:ACTIVE

Initial lifecycle status. Defaults to ACTIVE.

Available options:
ACTIVE,
FLAGGED,
BLOCKED
​
metadata
object

Arbitrary JSON object you attach to the business.

Response

Business created. Full business record returned (same shape as Get Business).

Full business detail. Extends BusinessListItem with metadata and comments.

​
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

​
legal_name
string | null

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).

​
region
string | null

ISO 3166-2 subdivision code (e.g. CA, NY for US states).

​
effective_name
string | null

Best available name: display_name if set, otherwise legal_name

​
status
enum<string>

Current status of this business

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

Map of feature name to latest status, e.g. {"KYB_REGISTRY": "Approved", "KYB_AML": "Approved"}

​
features_list
object[]

Same as features but as an 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

​
comments
object[]

Activity log and comments for this business

​
updated_at
string<date-time>