> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Business Data Model

> The Didit Business entity model — registry data, UBOs, officers, AML, documents, transactions, KYB session aggregates. Pay-per-call $2.00.

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](/entities/vendor-data-linking).                         |
| `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.                                                                                                     |

<Note>
  `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.
</Note>

## Status

| Field    | Type | Values                         | Description                                                                                      |
| -------- | ---- | ------------------------------ | ------------------------------------------------------------------------------------------------ |
| `status` | enum | `ACTIVE`, `FLAGGED`, `BLOCKED` | Controls enforcement for future sessions and transactions. See [lifecycle](/entities/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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<CardGroup cols={3}>
  <Card title="Operations" icon="gear" href="/entities/businesses/operations">
    Create, update, change status, delete.
  </Card>

  <Card title="KYB history" icon="clock-rotate-left" href="/entities/businesses/kyb-history">
    Retrieve every session tied to the business.
  </Card>

  <Card title="API reference" icon="code" href="/management-api/businesses/get">
    GET /v3/businesses/{vendor_data}/ schema.
  </Card>
</CardGroup>