Ctrlk

Entity And Role Management

Overview

The platform employs a sophisticated entity management system that follows the entity-role separation of concerns architecture. This document outlines the different entity types, relationships, and operations available in the system.

Overview of Entity Types

The platform supports the following main entity types:

Natural Persons

Natural persons represent individual human entities within the system. They can:

  • Be customers directly

  • Be part of joint persons

  • Be beneficial owners of legal entities

  • Act as proxies for other entities

  • Function as legal representatives of legal entities

Legal Entities

Legal entities represent companies, organizations, or other non-human entities. They can:

  • Be customers

  • Have beneficial owners

  • Have legal representatives

Joint Persons

Joint persons represent pairs of natural persons who act as a single entity, typically for joint accounts or shared ownership. They can:

  • Be customers

Beneficial Owners

Beneficial owners represent entities who ultimately own or control a legal entity. They are:

  • Always associated with a legal entity

  • Can be of different types (REAL_UBO_25, FICTIVE_UBO)

  • Can be natural persons

Legal Representatives

Legal representatives are entities authorized to act on behalf of legal entities. They are:

  • Always associated with a legal entity

Entity Relationships and References

The system establishes clear relationships between different entities:

Primary Entity Relationships

  1. Natural Person → Joint Person:

    • Two natural persons can form a joint person

  2. Natural Person → Proxy → Customer:

    • Natural persons can serve as proxies for customers (natural persons, joint persons, or legal entities)

  3. Legal Representative → Legal Entity:

    • Legal Representatives are related to legal entities

  4. Beneficial Owner → Legal Entity:

    • Beneficial owners are related to legal entities

Entity-Role Relationship

Entities and roles are separated in the system architecture:

  • Entities (natural persons, legal entities, joint persons, beneficial owners) represent the core identity

  • Roles (customer, proxy) represent functions that entities perform

This separation allows:

  • A single entity to have multiple roles

  • Clear status management for both entity and role

  • Independent onboarding and offboarding processes

Unified Entity View and Search Functionality

The platform provides a unified view and search functionality for all entity types:

Unified Entity Interface

The /entities endpoint provides a consistent interface for searching and retrieving all types of entities, with:

  • Common fields like globalId, entityId, entityName, entityType, entityStatus

  • Role information attached to each entity

Search Capabilities

Entity search supports:

  • Full-text search across entity names

  • Filtering by entity type

  • Filtering by entity status

  • Filtering by role

  • Pagination support

Example search query:

Entity Verification Processes

The verification process varies by entity type but shares common patterns:

Natural Person Verification

  1. Identification Verification:

    • Create identification verification via /entities/identification-verifications

    • Supports various identification types (VIDEO_IDENT)

    • Verification performed by external providers (e.g., WEB_ID)

  2. Document Verification:

    • Upload and verify identification documents

    • Document type, number, expiry date captured

Legal Entity Verification

  1. Company Information Verification:

    • Search for legal entities via /entities/vendor/legal-entities

    • Prepare legal entity via vendor services

    • Retrieve legal entity search results

  2. Document Verification:

    • Registry extracts

    • Verification of beneficial owners

    • Verification of legal representatives

Conclusion

The platform's entity management system provides a comprehensive and flexible framework for handling various entity types and their relationships. The entity-role separation ensures clean architecture while supporting complex business processes like onboarding and offboarding.

The unified entity view simplifies integration and provides consistent access to entity data, while type-specific operations offer the specialized functionality needed for each entity type's unique requirements.

Last updated