> ## 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.
# Entities
> Complete field reference for the Entity resource in the Zenoo CLM API.
# Entities
An entity represents a person or company under investigation. Entities are linked to cases via roles (Primary, UBO, Director, Shareholder) and track their verification status independently across cases.
## Resource fields
| Field | Type | Description |
| ---------------------- | ------ | ----------------------------------------------------------------------------- |
| `token` | string | Unique entity identifier (prefix `ent_`) |
| `type` | string | Entity type: `company` or `person` |
| `name` | string | Full name (company name or person full name) |
| `first_name` | string | First name (person entities only) |
| `last_name` | string | Last name (person entities only) |
| `date_of_birth` | string | Date of birth in `YYYY-MM-DD` format (person only) |
| `nationality` | string | ISO 3166-1 alpha-2 nationality code (person only) |
| `registration_number` | string | Company registration number (company only) |
| `country` | string | ISO 3166-1 alpha-2 country code |
| `company_type` | string | Legal entity type (company only) |
| `incorporation_date` | string | Date of incorporation `YYYY-MM-DD` (company only) |
| `industry` | string | Industry classification (company only) |
| `address_line_1` | string | Street address |
| `city` | string | City |
| `postcode` | string | Postal code |
| `email` | string | Email address |
| `phone` | string | Phone number |
| `verification_status` | string | Overall status: `Not Started`, `In Progress`, `Verified`, `Expired`, `Failed` |
| `last_verified_date` | string | ISO 8601 timestamp of last full verification |
| `risk_rating` | string | Entity risk rating: `High`, `Medium`, `Low` |
| `ownership_percentage` | number | Beneficial ownership percentage (UBOs only) |
| `role` | string | Role in case context: `Primary`, `UBO`, `Director`, `Shareholder` |
| `related_entities` | array | Related person entities (directors, UBOs) -- see below |
| `external_reference` | string | Your external entity identifier |
| `created_at` | string | ISO 8601 timestamp of creation |
| `updated_at` | string | ISO 8601 timestamp of last modification |
## Related entity object
When retrieving a company entity, `related_entities` contains linked persons:
| Field | Type | Description |
| ---------------------- | ------ | -------------------------------------- |
| `token` | string | Person entity token |
| `name` | string | Full name |
| `role` | string | Role: `Director`, `UBO`, `Shareholder` |
| `ownership_percentage` | number | Ownership percentage (UBOs only) |
| `verification_status` | string | Individual verification status |
## Company-to-Person Verification Flow
When you verify a company, Zenoo extracts directors and beneficial owners from the company registry and screens each one for PEP/sanctions/adverse media. If any individual requires further identity verification (document check, biometrics), you initiate a separate Person Verification for that specific person.
Submit the company via `POST /api/gateway/execute/{project_hash}/api` (sync) or `/init` (async). Include any known directors and UBOs in the request.
Zenoo retrieves the company record from the official registry and discovers directors, shareholders, and beneficial owners — including any not provided in your request.
Every individual (submitted and discovered) is automatically screened for PEP, sanctions, and adverse media. Results appear in the `directors[]` and `beneficial_owners[]` arrays of the [compliance report](/data-model/compliance-report).
For individuals who require identity verification (e.g., UBOs with >25% ownership), initiate a Person Verification:
```bash theme={null}
POST /api/gateway/execute/{project_hash}/kyc/init
```
Pass the individual's details and use the returned `start` token to send them a verification link. See [Person Verification Request Fields](/data-model/request-fields-kyc).
Once all individual verifications complete, the company's overall `verification_status` updates and the `identity_verified` flag on each beneficial owner reflects their current state.
You do not need to wait for all Person Verifications to complete before acting on the company results. The company verification verdict and screening results are available immediately. Person Verification results update the individual records independently.
## Company entity example
```json theme={null}
{
"token": "ent_abc123",
"type": "company",
"name": "Acme Holdings Ltd",
"registration_number": "12345678",
"country": "GB",
"company_type": "Private Limited Company (Ltd)",
"incorporation_date": "2015-03-15",
"industry": "Financial Services",
"address_line_1": "123 High Street",
"city": "London",
"postcode": "EC1A 1BB",
"verification_status": "Verified",
"last_verified_date": "2026-02-16T11:35:00Z",
"risk_rating": "Medium",
"related_entities": [
{
"token": "ent_dir456",
"name": "Jane Smith",
"role": "Director",
"verification_status": "Verified"
},
{
"token": "ent_ubo789",
"name": "John Doe",
"role": "UBO",
"ownership_percentage": 75,
"verification_status": "Verified"
}
],
"external_reference": "YOUR-ENT-001",
"created_at": "2026-02-16T10:00:00Z",
"updated_at": "2026-02-16T11:35:00Z"
}
```
## Person entity example
```json theme={null}
{
"token": "ent_ubo789",
"type": "person",
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1975-11-10",
"nationality": "GB",
"country": "GB",
"verification_status": "Verified",
"last_verified_date": "2026-02-16T11:00:00Z",
"risk_rating": "Medium",
"role": "UBO",
"ownership_percentage": 75,
"external_reference": "YOUR-UBO-001",
"created_at": "2026-02-16T10:00:00Z",
"updated_at": "2026-02-16T11:00:00Z"
}
```
## Related endpoints
| Endpoint | Method | Description |
| --------------------------------------- | ------ | -------------------------------- |
| `GET /v1/entities` | GET | List entities with filters |
| `POST /v1/entities` | POST | Create a new entity |
| `GET /v1/entities/{token}` | GET | Get entity details |
| `PATCH /v1/entities/{token}` | PATCH | Update entity fields |
| `GET /v1/entities/{token}/cases` | GET | List cases for an entity |
| `GET /v1/entities/{token}/checks` | GET | List checks for an entity |
| `POST /v1/entities/{token}/ai-research` | POST | Trigger AI research on an entity |
## See also
* [Entity Lifecycle Guide](/guides/entity-lifecycle)
* [Status Enums Reference](/reference/status-enums)