# 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:

```
GET /entities?searchText=Smith&entityType=NATURAL_PERSON&entityStatus=ACTIVE
```

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


---

# 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.wawex.ai/documentation/4_entity_role_management_after_refactor.md?ask=<question>
```

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.