Skip to main content
PATCH
curl

Overview

Moves a Business entity between ACTIVE, FLAGGED, and BLOCKED. See entity lifecycle for the full state machine.

When to use it

  • Block a sanctioned or confirmed-fraudulent business.
  • Flag a business pending manual review.
  • Unblock after remediation.
  • Propagate external signals from your own compliance systems.

Notes

  • Valid values: ACTIVE, FLAGGED, BLOCKED.
  • Passing a reason string is recommended — it is persisted and surfaced in the audit log and webhook payload.
  • BLOCKED businesses have all new Business Verification (KYB) sessions auto-declined and all new transactions auto-declined, including when they appear as counterparty.
  • Emits business.status.updated with previous_status, status, and reason.

Enforcement

Permissions

Role must grant update-status: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
status
enum<string>
required

New lifecycle status. BLOCKED also adds the vendor_data to the system blocklist.

Available options:
ACTIVE,
FLAGGED,
BLOCKED

Response

Business status updated. Full business record returned.

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>