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. For detailed information about roles that natural persons can have, see Role 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.

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.

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. For information about natural persons acting as beneficial owners, see 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. For information about natural persons acting as legal representatives, see 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

  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.

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. For detailed information about onboarding processes, see Onboarding. For comprehensive information about document management, see Document Management.

Last updated