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" }
]
}'
- 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
