Skip to main content

​
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

FieldTypeDescription
tokenstringUnique entity identifier (prefix ent_)
typestringEntity type: company or person
namestringFull name (company name or person full name)
first_namestringFirst name (person entities only)
last_namestringLast name (person entities only)
date_of_birthstringDate of birth in YYYY-MM-DD format (person only)
nationalitystringISO 3166-1 alpha-2 nationality code (person only)
registration_numberstringCompany registration number (company only)
countrystringISO 3166-1 alpha-2 country code
company_typestringLegal entity type (company only)
incorporation_datestringDate of incorporation YYYY-MM-DD (company only)
industrystringIndustry classification (company only)
address_line_1stringStreet address
citystringCity
postcodestringPostal code
emailstringEmail address
phonestringPhone number
verification_statusstringOverall status: Not Started, In Progress, Verified, Expired, Failed
last_verified_datestringISO 8601 timestamp of last full verification
risk_ratingstringEntity risk rating: High, Medium, Low
ownership_percentagenumberBeneficial ownership percentage (UBOs only)
rolestringRole in case context: Primary, UBO, Director, Shareholder
related_entitiesarrayRelated person entities (directors, UBOs) — see below
external_referencestringYour external entity identifier
created_atstringISO 8601 timestamp of creation
updated_atstringISO 8601 timestamp of last modification
When retrieving a company entity, related_entities contains linked persons:
FieldTypeDescription
tokenstringPerson entity token
namestringFull name
rolestringRole: Director, UBO, Shareholder
ownership_percentagenumberOwnership percentage (UBOs only)
verification_statusstringIndividual 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.
1

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.
2

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.
3

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.
4

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.
5

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"
}
EndpointMethodDescription
GET /v1/entitiesGETList entities with filters
POST /v1/entitiesPOSTCreate a new entity
GET /v1/entities/{token}GETGet entity details
PATCH /v1/entities/{token}PATCHUpdate entity fields
GET /v1/entities/{token}/casesGETList cases for an entity
GET /v1/entities/{token}/checksGETList checks for an entity
POST /v1/entities/{token}/ai-researchPOSTTrigger AI research on an entity

​
See also