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

# Entity Lifecycle

> Understand entity types, roles, verification statuses, and access patterns in the Zenoo CLM platform.

# Entity Lifecycle

Entities represent the people and companies under investigation. Every case revolves around a primary entity and optionally includes related entities such as directors, UBOs, and shareholders.

## Entity types

Zenoo supports two entity types, each with distinct verification requirements:

| Type      | Description                           | Verification scope                                        |
| --------- | ------------------------------------- | --------------------------------------------------------- |
| `company` | A legal entity (Ltd, LLC, GmbH, etc.) | Registry check, company screening, director/UBO screening |
| `person`  | An individual (natural person)        | Identity verification, biometrics, individual screening   |

## Entity roles

When an entity is linked to a case, it is assigned a role that determines which checks are required:

| Role          | Description                                | Check requirements                                                                      |
| ------------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
| `Primary`     | The main entity under investigation        | Screening (required), Adverse Media (required), Identity (N/A for companies)            |
| `UBO`         | Ultimate Beneficial Owner (>25% ownership) | Identity (required), Screening (required), Address (required), Adverse Media (required) |
| `Director`    | Company director or officer                | Identity (required), Screening (required), Adverse Media (required)                     |
| `Shareholder` | Non-UBO shareholder                        | Identity (required), Screening (required)                                               |

<Info>
  For UBOs and Directors, if the entity is assessed as High risk, Source of Wealth (SOW) checks are automatically added as an Enhanced Due Diligence (EDD) requirement.
</Info>

## Verification status lifecycle

Each entity tracks its overall verification status independently of any specific case.

```mermaid theme={null}
stateDiagram-v2
    [*] --> Not_Started
    Not_Started --> In_Progress : First check begins
    In_Progress --> Verified : All required checks pass
    In_Progress --> Failed : Any required check fails
    Verified --> Expired : Validity period exceeded
    Expired --> In_Progress : Re-verification initiated
    Failed --> In_Progress : Retry or new check
```

| Status        | Description                                            |
| ------------- | ------------------------------------------------------ |
| `Not Started` | No checks have been executed for this entity           |
| `In Progress` | At least one check is running or pending               |
| `Verified`    | All required checks completed with passing results     |
| `Expired`     | Previous verification has exceeded its validity period |
| `Failed`      | One or more required checks returned a failing result  |

## Entity creation

### Creating a company entity with related persons

```bash theme={null}
curl -X POST https://api.zenoo.com/v1/entities \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "name": "Acme Holdings Ltd",
    "registration_number": "12345678",
    "country": "GB",
    "directors": [
      { "first_name": "Jane", "last_name": "Smith", "role": "Director" }
    ],
    "ubos": [
      { "first_name": "John", "last_name": "Doe", "ownership_percentage": 75, "role": "UBO" }
    ]
  }'
```

When you create a company entity with directors and UBOs, Zenoo automatically:

1. Creates individual person entity records for each director and UBO
2. Links them to the parent company entity with the correct role
3. Returns all entity tokens in the response

### Creating a standalone person entity

```bash theme={null}
curl -X POST https://api.zenoo.com/v1/entities \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "person",
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1980-05-20",
    "nationality": "GB",
    "country": "GB"
  }'
```

## Cross-case entity reuse

Entities persist across cases. When a person entity (e.g., a UBO) appears in a new case, Zenoo checks for existing valid checks through the "Verify Once, Reference Many" system:

1. The system looks up previous passing checks for the same entity
2. If a valid, non-expired check exists, a `Reused` check is created instead of a new one
3. The reused check references the original check and source case

This prevents redundant verification while preserving full provenance.

### Check validity periods

| Check Category | Default Validity |
| -------------- | ---------------- |
| Identity       | 365 days         |
| Screening      | 90 days          |
| Company        | 180 days         |
| Financial      | 365 days         |
| EDD            | 180 days         |

## Access patterns

### Entity-centric access

Retrieve all cases and checks for a specific entity:

```bash theme={null}
# Get entity with all related cases
curl -X GET "https://api.zenoo.com/v1/entities/ent_abc123?include=cases,checks" \
  -H "Authorization: Bearer your-api-key"
```

### Case-centric access

Retrieve all entities linked to a specific case:

```bash theme={null}
# Get case with all entities
curl -X GET "https://api.zenoo.com/v1/cases/cas_xyz789/entities" \
  -H "Authorization: Bearer your-api-key"
```

## Next steps

* [Case Lifecycle](/guides/case-lifecycle). How cases flow from creation to closure.
* [Check Orchestration](/guides/check-orchestration). How checks are auto-created for entity roles.
* [Entities Data Model](/data-model/entities). Full field reference for entity resources.