# Entity And Role Management ## Overview The platform uses 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 For detailed information about natural person management and preparation, see [Natural Person Management](/documentation/entity_role_management_after_refactor/natural_person_management.md). For detailed information about roles that natural persons can have, see [Role Management](/documentation/entity_role_management_after_refactor/roles_management.md). ### Legal Entities Legal entities represent companies, organizations, or other non-human entities. They can: * Be customers * Have beneficial owners * Have legal representatives For detailed information about legal entity management and preparation, see [Legal Entity Management](/documentation/entity_role_management_after_refactor/legal_entity_management.md). ### 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 For detailed information about joint person preparation, see [Natural Person Management](/documentation/entity_role_management_after_refactor/natural_person_management.md). ### 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 For detailed information about beneficial owner management, see [Legal Entity Management](/documentation/entity_role_management_after_refactor/legal_entity_management.md). For information about natural persons acting as beneficial owners, see [Natural Person Management](/documentation/entity_role_management_after_refactor/natural_person_management.md). ### Legal Representatives Legal representatives are entities authorized to act on behalf of legal entities. They are: * Always associated with a legal entity * Can be natural persons For detailed information about legal representative management, see [Legal Entity Management](/documentation/entity_role_management_after_refactor/legal_entity_management.md). For information about natural persons acting as legal representatives, see [Natural Person Management](/documentation/entity_role_management_after_refactor/natural_person_management.md). ## 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) * For detailed proxy role information, see [Role Management](/documentation/entity_role_management_after_refactor/roles_management.md) 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 For comprehensive information about role management and assignment, see [Role Management](/documentation/entity_role_management_after_refactor/roles_management.md). ## 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, entityId, and globalId * Filtering by entity type * Filtering by entity status * Filtering by role * Filtering by Global ID (12-character identifier) * Filtering by Entity ID (UUID format) * Pagination support (cursor-based with configurable limit) Example search queries: ``` GET /entities?searchText=Smith&entityType=NATURAL_PERSON&entityStatus=ACTIVE GET /entities?globalId=ABC123DEF456 GET /entities?entityId=550e8400-e29b-41d4-a716-446655440000&role=CUSTOMER GET /entities?limit=50&cursor=next_page_token ``` ## 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. For detailed information about role management and assignment, see [Role Management](/documentation/entity_role_management_after_refactor/roles_management.md). For detailed information about onboarding processes, see [Onboarding](/documentation/entity_role_management_after_refactor/onboarding.md). For comprehensive information about document management, see [Document Management](/documentation/entity_role_management_after_refactor/document_management.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tradevest.ai/documentation/entity_role_management_after_refactor.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.