Business Data Model

This page documents every field on a Business entity and how Didit populates each one.

Identity fields

Field	Type	Description
`uuid`	UUID	Didit-assigned primary key. Stable and unique.
`didit_internal_id`	string	Human-readable internal identifier.
`vendor_data`	string	Your identifier for the business. Unique per application. Read more.
`display_name`	string	Override name shown in the console. Defaults to `legal_name` or `vendor_data`.
`legal_name`	string	Legal company name as registered — propagated from the latest approved Business Verification (KYB) session’s registry lookup.
`registration_number`	string	Official company registration number — propagated from registry.
`country_code`	string (ISO 3166-1 alpha-3)	Country of incorporation.

legal_name, registration_number, and country_code are read-only when derived from a verified registry lookup. They can be manually overridden in the console or via PATCH /v3/businesses/{vendor_data}/, but overrides are flagged in the audit log.

Status

Field	Type	Values	Description
`status`	enum	`ACTIVE`, `FLAGGED`, `BLOCKED`	Controls enforcement for future sessions and transactions. See lifecycle.

Session aggregate fields

Field	Type	Description
`session_count`	int	Total Business Verification (KYB) sessions ever created for this business
`approved_count`	int	Sessions finished with `APPROVED`
`declined_count`	int	Sessions finished with `DECLINED`
`in_review_count`	int	Sessions currently `IN_REVIEW`
`features`	object	Latest status of each KYB feature across sessions

The `features` map

{
  "kyb_registry": "APPROVED",
  "kyb_company_aml": "APPROVED",
  "kyb_documents": "APPROVED",
  "kyb_key_people": "IN_REVIEW"
}

Feature values: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED. Use the features map as the fast path to check whether a business is fully verified right now without iterating all sessions.

Activity timestamps

Field	Type	Updated when
`first_session_at`	ISO timestamp	First Business Verification (KYB) session was created
`last_session_at`	ISO timestamp	Most recent session was created or updated
`last_activity_at`	ISO timestamp	Any change — session, transaction, status, profile, notes
`created_at`	ISO timestamp	Entity row was created
`updated_at`	ISO timestamp	Entity row was last updated

Metadata

Field	Type	Description
`metadata`	object (JSON)	Free-form JSON you control
`tags[]`	array	Console/API-managed tags

Relations (not stored on the business row)

Relation	How to access
Business Verification (KYB) sessions	`GET /v3/sessions?vendor_data=<value>`
Linked users (officers, UBOs, directors)	Surfaced on the business detail page in the console; derived from the latest approved Business Verification (KYB) session
Transactions (as applicant or counterparty)	Filter transactions by business `vendor_data`
Documents	Via Business Verification (KYB) session decisions
AML hits	Via Business Verification (KYB) session decisions

Example response

{
  "uuid": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "didit_internal_id": "B-2026-00018",
  "vendor_data": "biz-acme",
  "display_name": "Acme Corp",
  "legal_name": "Acme Corporation Limited",
  "registration_number": "12345678",
  "country_code": "GBR",
  "status": "ACTIVE",
  "session_count": 2,
  "approved_count": 1,
  "declined_count": 0,
  "in_review_count": 1,
  "features": {
    "kyb_registry": "APPROVED",
    "kyb_company_aml": "APPROVED",
    "kyb_documents": "APPROVED",
    "kyb_key_people": "IN_REVIEW"
  },
  "first_session_at": "2025-09-01T12:00:00Z",
  "last_session_at": "2026-04-01T09:00:00Z",
  "last_activity_at": "2026-04-16T10:00:00Z",
  "metadata": { "partner": "Acme Holdings" }
}

Next steps

Operations

Create, update, change status, delete.

KYB history

Retrieve every session tied to the business.

API reference

GET /v3/businesses// schema.

Overview

Pricing

Workflows & Verification

Review & Operations

Entities (Users & Businesses)

Settings & Customization

Security & Compliance

Resources

Identity fields

Status

Session aggregate fields

The `features` map

Activity timestamps

Metadata

Relations (not stored on the business row)

Example response

Next steps

Operations

KYB history

API reference

​Identity fields

​Status

​Session aggregate fields

​The features map

​Activity timestamps

​Metadata

​Relations (not stored on the business row)

​Example response

​Next steps

Operations

KYB history

API reference

Identity fields

Status

Session aggregate fields

The `features` map

Activity timestamps

Metadata

Relations (not stored on the business row)

Example response

Next steps