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

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.

Company Verification

Submit the company via POST /api/gateway/execute/{project_hash}/api (sync) or /init (async). Include any known directors and UBOs in the request.

Registry Extraction

Zenoo retrieves the company record from the official registry and discovers directors, shareholders, and beneficial owners — including any not provided in your request.

Automatic Screening

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.

Identity Verification (if needed)

For individuals who require identity verification (e.g., UBOs with >25% ownership), initiate a Person Verification:

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.

Consolidated Results

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

{
  "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

{
  "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"
}

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

Getting Started

Use-Case Guides

Platform Concepts

Domain Concepts

Data Model

Entities

Entities

Resource fields

Company-to-Person Verification Flow

Company entity example

Person entity example

See also

​Entities

​Resource fields

​Related entity object

​Company-to-Person Verification Flow

​Company entity example

​Person entity example

​Related endpoints

​See also

Entities

Resource fields

Related entity object

Company-to-Person Verification Flow

Company entity example

Person entity example

Related endpoints

See also