Skip to main content
PATCH
/
v3
/
businesses
/
{vendor_data}
curl
curl -X PATCH 'https://verification.didit.me/v3/businesses/company-123/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"display_name": "Acme Corp", "status": "FLAGGED"}'
{
  "didit_internal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "vendor_data": "company-123",
  "display_name": "Acme Corp",
  "legal_name": "Acme Trading Ltd",
  "status": "FLAGGED",
  "metadata": {
    "industry": "fintech",
    "risk_level": "low"
  },
  "updated_at": "2026-03-15T10:30:00Z"
}

​
Overview

Updates mutable fields on a Business entity. Fields populated from registry lookups (legal_name, registration_number, country_code) become read-only after the first approved Business Verification (KYB) session.

​
When to use it

  • Rename — set a better display_name for internal views.
  • Update metadata — move a business between internal tiers, record an internal note, change tags.
  • Override registry data (with caution) — overrides are accepted but flagged in the audit log.

​
Notes

  • vendor_data in the URL cannot be changed via this endpoint.
  • Emits a business.data.updated webhook with a changed_fields array.

​
Permissions

Role must grant update:businesses.

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
vendor_data
string
required

Your unique identifier for the business (free-form string, NOT a UUID).

Body

application/json

Partial-update body. Provide only the fields you want to change.

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

​
status
enum<string>

Business lifecycle status. Setting BLOCKED automatically adds the vendor_data to the system blocklist; flipping away from BLOCKED removes that blocklist entry.

Available options:
ACTIVE,
FLAGGED,
BLOCKED
​
metadata
object

Arbitrary JSON object you attach to the business. Fully replaces the existing metadata on update — merge client-side if you only want to add keys.

Response

Business updated. The full updated business record is returned.

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>