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)

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.

Verification status lifecycle

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

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

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:

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

Creating a standalone person entity

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:

The system looks up previous passing checks for the same entity
If a valid, non-expired check exists, a Reused check is created instead of a new one
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:

# 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:

# 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. How cases flow from creation to closure.
Check Orchestration. How checks are auto-created for entity roles.
Entities Data Model. Full field reference for entity resources.

Getting Started

Use-Case Guides

Platform Concepts

Domain Concepts

Data Model

Entity Lifecycle

Entity Lifecycle

Entity types

Entity roles

Verification status lifecycle

Entity creation

Creating a standalone person entity

Cross-case entity reuse

Check validity periods

Access patterns

Entity-centric access

Case-centric access

Next steps

​Entity Lifecycle

​Entity types

​Entity roles

​Verification status lifecycle

​Entity creation

​Creating a company entity with related persons

​Creating a standalone person entity

​Cross-case entity reuse

​Check validity periods

​Access patterns

​Entity-centric access

​Case-centric access

​Next steps

Entity Lifecycle

Entity types

Entity roles

Verification status lifecycle

Entity creation

Creating a company entity with related persons

Creating a standalone person entity

Cross-case entity reuse

Check validity periods

Access patterns

Entity-centric access

Case-centric access

Next steps