Skip to main content
POST
/
v3
/
businesses
/
create
curl --request POST \
  --url https://verification.didit.me/v3/businesses/create/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "vendor_data": "company-456",
  "legal_name": "New Corp Ltd",
  "country_code": "US"
}
'
{
  "didit_internal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendor_data": "<string>",
  "display_name": "<string>",
  "legal_name": "<string>",
  "registration_number": "<string>",
  "country_code": "<string>",
  "region": "<string>",
  "effective_name": "<string>",
  "status": "Active",
  "session_count": 123,
  "approved_count": 123,
  "declined_count": 123,
  "in_review_count": 123,
  "features": {},
  "features_list": [
    {
      "feature": "<string>",
      "status": "<string>"
    }
  ],
  "last_session_at": "2023-11-07T05:31:56Z",
  "first_session_at": "2023-11-07T05:31:56Z",
  "last_activity_at": "2023-11-07T05:31:56Z",
  "tags": [
    {
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "color": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "metadata": {},
  "comments": [
    {
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "comment_type": "<string>",
      "comment": "<string>",
      "actor_email": "<string>",
      "actor_name": "<string>",
      "previous_status": "<string>",
      "new_status": "<string>",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ],
  "updated_at": "2023-11-07T05:31:56Z"
}

​
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

​
display_name
string | null

Custom display name for this business

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

Initial status (defaults to Active)

Available options:
Active,
Flagged,
Blocked
​
metadata
object

Custom metadata JSON

Response

201 - application/json

Business created.

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>