# 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](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/natural_person_management). For detailed information about roles that natural persons can have, see [Role Management](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/roles_management).

### 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](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/legal_entity_management).

### 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](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/natural_person_management).

### 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](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/legal_entity_management). For information about natural persons acting as beneficial owners, see [Natural Person Management](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/natural_person_management).

### 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](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/legal_entity_management). For information about natural persons acting as legal representatives, see [Natural Person Management](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/natural_person_management).

## 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](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/roles_management)
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](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/roles_management).

## 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](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/roles_management). For detailed information about onboarding processes, see [Onboarding](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/onboarding). For comprehensive information about document management, see [Document Management](https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/document_management).