Entity-Role Model: Overview

Overview

This document outlines the significant changes made to the TradeVest API structure, specifically the migration from the previous customers.yaml to the new architecture using entities.yaml and roles.yaml. This restructuring provides better separation of concerns, improves modularity, and enhances maintainability.

Core Architectural Changes

1. API Division into Separate Domains

The previous monolithic customers.yaml has been divided into two specialized API domains:

  • entities.yaml: Manages entity data (natural persons, legal entities, joint persons, beneficial owners)

  • roles.yaml: Manages role assignments (customers, proxies)

This separation aligns with dorelease-test-driven design principles, providing clearer boundaries between different business concepts.

2. Entity-Role Relationship Model

The new architecture follows a more flexible entity-role relationship model:

  • Entities represent real-world actors (people or organizations)

  • Roles represent functions that these entities perform in the system

Entity Management (entities.yaml)

New Entity Types

1. Joint Persons

  • New endpoints for managing joint persons:

    • POST /entities/joint-persons: Create joint person

    • GET /entities/joint-persons: List joint persons

    • GET /entities/joint-persons/{jointPersonId}: Get specific joint person

    • PATCH /entities/joint-persons/{jointPersonId}: Update joint person

  • New schemas:

    • JointPersonData: Core data structure

    • JointPerson: Complete joint person object

    • JointPersonUpdate: Structure for updates

2. Legal Entities

  • New endpoints for managing legal entities:

    • POST /entities/legal-entities: Create legal entity

    • GET /entities/legal-entities: List legal entities

    • GET /entities/legal-entities/{legalEntityId}: Get specific legal entity

    • PATCH /entities/legal-entities/{legalEntityId}: Update legal entity

    • GET /entities/vendor/legal-entities: Search for legal entities

    • POST /entities/vendor/legal-entities: Prepare legal entity data

    • GET /entities/vendor/legal-entities/{searchId}: Get search results

3. Natural Persons

  • Path prefix changed to /entities/natural-persons

  • Roles have been removed from natural persons GET endpoint (Natural persons can now be queried with their roles using the unified /entities endpoint with appropriate filters)

  • Enhanced data model for better identity management

  • New endpoints for managing natural persons:

    • POST /entities/natural-persons: Create natural person

    • GET /entities/natural-persons: List natural persons

    • GET /entities/natural-persons/{naturalPersonId}: Get specific natural person

    • PATCH /entities/natural-persons/{naturalPersonId}: Update natural person

    • POST /entities/natural-persons/{naturalPersonId}/identification: Create natural person identification

    • GET /entities/natural-persons/search/nace-sectors: Search for NACE sectors

    • POST /entities/identification-verifications: Create identification verification

    • GET /entities/identification-verifications: List identification verifications

    • GET /entities/identification-verifications/{identificationVerificationId}: Get specific identification verification

Entity Status Enums

The system now includes specialized status enums for different entity types:

JointPersonStatusEnum

  • CREATED

  • REVIEW

  • REJECTED

  • INACTIVE

  • PENDING

  • ACTIVE

  • SUSPENDED

  • ARCHIVED

  • RECEIVED

  • INVALID

  • SUSPENDED_COMPLIANCE

LegalEntityStatusEnum

  • CREATED

  • REVIEW

  • REJECTED

  • INACTIVE

  • PENDING

  • ACTIVE

  • SUSPENDED

  • ARCHIVED

  • RECEIVED

  • INVALID

  • SUSPENDED_COMPLIANCE

New Entity Relationship Management

Beneficial Owners

  • Enhanced endpoints for managing entities that are beneficial owners of legal entities:

    • POST /entities/{legalEntityId}/beneficial-owners

    • GET /entities/{legalEntityId}/beneficial-owners

    • GET /entities/beneficial-owners/{beneficialOwnerId}

    • PATCH /entities/beneficial-owners/{beneficialOwnerId}

Key Changes in Beneficial Owner Model

The beneficial owner management has undergone significant structural changes similar to those in the proxy role:

  • Entity-centric approach: Beneficial owners are now associated with legal entities directly rather than with customers

    • In the previous model, beneficial owners were created via /customers/natural-persons/{customerId}/beneficial-owners

    • In the new model, they are created via /entities/{legalEntityId}/beneficial-owners

  • Path parameter changes:

    • Previous: customerId in paths referred to the customer the beneficial owner was assigned to

    • New: legalEntityId directly refers to the legal entity that has beneficial owners

  • Relationship model improvements:

    • More accurate representation of real-world relationship (beneficial owners belong to legal entities, not to customer roles)

    • Clear separation between entity data and role assignments

    • More direct path to manage beneficial ownership without the intermediate customer role

  • Standardized endpoint structure:

    • Consistent with the global API architecture shift

    • Follow the same pattern as other entity relationships

    • Simplified URL structure for better API navigation

These changes align with the broader architectural goal of properly separating entities from roles, resulting in a more intuitive and accurate data model that better reflects real-world business relationships.

Legal Representatives

  • Enhanced endpoints:

    • POST /entities/{legalEntityId}/legal-representatives

    • GET /entities/{legalEntityId}/legal-representatives

    • GET /entities/legal-representatives/{legalRepresentativeId}

    • PATCH /entities/legal-representatives/{legalRepresentativeId}

    • DELETE /entities/legal-representatives/{legalRepresentativeId}

Entity Search and Verification

  • Legal entity search endpoints (also listed in the "Legal Entities" section above):

    • Provide functionality to search, prepare and retrieve legal entity data from external sources

    • Used for KYC/AML verification and pre-population of legal entity data

  • Enhanced identification verification:

    • Moved to /entities/identification-verifications

    • Improved data model and processing flow

Reference Model Changes

  • Entities will now only contain identifiers of related entities rather than nested objects:

    • For example, a joint person will contain natural person IDs (firstNaturalPersonId, secondNaturalPersonId) instead of full natural person objects

    • Similarly, legal entities will reference beneficial owners and legal representatives by ID

    • This approach reduces payload size and improves consistency in the API

    • To retrieve related entity details, use the appropriate entity endpoints with the referenced IDs

Role Management (roles.yaml)

Customer Role

  • New endpoints:

    • POST /roles/customers: Assign customer role to an entity

    • GET /roles/customers: List customer roles

    • GET /roles/customers/{customerId}: Get specific customer role

    • PATCH /roles/customers/{customerId}: Update customer role

Proxy Role

  • New endpoints:

    • POST /roles/proxies: Assign proxy role

    • GET /roles/proxies: List proxies

    • GET /roles/proxies/{proxyId}: Get specific proxy

    • PATCH /roles/proxies/{proxyId}: Update proxy

Key Changes in Proxy Model

The proxy role has undergone significant structural changes:

  • Entity-centric approach: Proxies are now associated with entities rather than customers

    • In the previous model, proxy was created via /natural-persons/{naturalPersonId}/proxy and linked to customers

    • In the new model, proxies are created directly via /roles/proxies and linked to any entity type

  • ProxyData model changes:

    • Added entityId field to replace the previous customerId

    • Added entityType field to specify the type of entity (natural person, legal entity, joint person)

    • This allows proxies to be associated with any entity type, not just customers

  • Search and filtering:

    • New query parameter entityId for filtering proxies by entity

  • Improved relationship model:

    • Clear separation between the natural person who acts as a proxy and the entity they represent

    • More flexible model that supports various business relationships

These changes align with the overall architecture shift toward clearly separating entities from roles, providing greater flexibility in modeling business relationships and processes.

Customer Labels

  • Endpoints moved to roles API:

    • GET /roles/customer-labels: List customer labels

    • PATCH /roles/customer-labels/{labelName}: Update label

    • DELETE /roles/customer-labels/{labelName}: Delete label

    • PATCH /roles/customer-labels/{labelName}/customers: Add label to customers

    • POST /roles/customer-labels/{labelName}/customers: Remove label from customers

Onboarding and Offboarding Process Changes

The onboarding process has been restructured to align with the entity-role architecture, with specific focuses for each type of onboarding:

Entity Onboarding (entities.yaml)

  • New model: EntityOnboardingData focused on entity-centric onboarding

  • New endpoints:

    • POST /entities/onboardings: Start entity onboarding

    • GET /entities/onboardings: List entity onboardings

    • GET /entities/onboardings/{onboardingId}: Get entity onboarding details

Entity Onboarding Purpose:

  • Primarily used for onboarding new beneficial owners for an already active legal entity customer

  • Requires an active legal entity customer to onboard a new beneficial owner associated with it

  • Does not handle complete customer onboarding flows

Role Onboarding (roles.yaml)

  • New model: RoleOnboardingData focused on role-centric onboarding

  • New endpoints:

    • POST /roles/onboardings: Start role onboarding

    • GET /roles/onboardings: List role onboardings

    • GET /roles/onboardings/{onboardingId}: Get role onboarding details

Role Onboarding Types:

Customer Onboarding

  • Comprehensive onboarding process that handles:

    • Onboarding of the customer role

    • Onboarding of all proxies associated with the customer

    • Onboarding of all beneficial owners associated with the customer (for legal entity customers)

  • Used for onboarding new customers to the system

  • Primary method for complete entity onboarding in the system

Proxy Onboarding

  • Specifically for onboarding new proxies for existing, already active customers

  • Only handles the proxy role and not the entire customer profile

  • Used when an active customer needs a new proxy added

Onboarding Process Flow Change

The new onboarding architecture reflects a more focused approach:

  • Customer role onboarding handles the comprehensive onboarding of customers and their related entities

  • Entity onboarding is specialized for beneficial owner onboarding for existing customers

  • Proxy onboarding is specialized for adding new proxies to existing customers

This change ensures each onboarding process has a clear, specific purpose while maintaining the separation between entities and roles.

Offboarding Process

  • Offboarding endpoints will be added soon to both entity and role APIs

  • Will support offboarding operations similar to the onboarding process

  • Will replace any previous offboarding functionality

Entity Offboarding (entities.yaml)

  • New model: EntityOffboardingData focused on entity-centric offboarding

  • New endpoints:

    • POST /entities/offboardings: Start entity offboarding

    • GET /entities/offboardings: List entity offboardings

    • GET /entities/offboardings/{offboardingId}: Get entity offboarding details

Entity Offboarding Purpose:

  • Primarily used for offboarding beneficial owners from an active legal entity customer

  • Supports inactivation of a beneficial owner while maintaining the legal entity customer

  • Does not handle complete customer offboarding flows

Role Offboarding (roles.yaml)

  • New model: RoleOffboardingData focused on role-centric offboarding

  • New endpoints:

    • POST /roles/offboardings: Start role offboarding

    • GET /roles/offboardings: List role offboardings

    • GET /roles/offboardings/{offboardingId}: Get role offboarding details

Role Offboarding Types:

Customer Offboarding

  • Comprehensive offboarding process that handles:

    • Offboarding of the customer role

    • Offboarding of all proxies associated with the customer

    • Offboarding of all beneficial owners associated with the customer (for legal entity customers)

  • Used for completely inactivating customers from the system

  • Primary method for complete entity offboarding

Proxy Offboarding

  • Specifically for offboarding proxies from existing, active customers

  • Only handles the proxy role and not the entire customer profile

  • Used when an active customer needs a proxy inactivated

Offboarding Process Flow Change

The new offboarding architecture reflects a more focused approach aligned with the entity-role separation:

  • Customer role offboarding handles the comprehensive offboarding of customers and their related entities

  • Entity offboarding is specialized for beneficial owner inactivation from existing customers

  • Proxy offboarding is specialized for inactivating proxies from existing customers

This change ensures each offboarding process has a clear, specific purpose while maintaining the separation between entities and roles, mirroring the structure established for onboarding processes.

Webhook Notifications

The following webhook endpoints are currently available to support the entity-role architecture:

Entity-Related Webhooks

  • /natural-person-notification: For natural person events

  • /joint-person-notification: For joint person events (new)

  • /identification-verification-notification: For verification events

  • /beneficial-owner-notification: For beneficial owner events

  • /legal-entity-notification: For legal entity events (new)

  • /legal-representative-notification: For legal representative events (new)

Role-Related Webhooks

  • /customer-notification: For customer role events

  • /proxy-notification: For proxy role events

  • /labels-update-notification: For customer label updates

Process Webhooks

  • /onboarding-notification: For onboarding process updates

  • /offboarding-notification: For offboarding process updates

Get Entities Endpoint

A new endpoint /entities has been added to provide a unified view of all entities in the system, regardless of their type. This replaces the previous role-based organization of entities.

Key features:

  • Returns consolidated entity information

  • No longer includes roles (roles are now queried separately)

  • Provides better filtering and pagination options

  • Supports searching across entity types

Document Management Changes

1. Improved Document API Structure

The document management API has been restructured to follow a similar separation pattern as the main entity-role architecture:

  • Path Prefix Changes:

    • Previous API paths using /documents/ are now available under /v2/documents/

    • Legacy endpoints are preserved with -old suffix in their operation IDs for backward compatibility

  • New Document Resource Types:

    • Added dedicated DocumentResourceTypeEnum with values:

      • NATURAL_PERSON

      • LEGAL_ENTITY

      • PARTNER_USER

      • CUSTOMER

      • PROXY

  • Standardized Document Status Enum:

    • Added dedicated DocumentStatusEnum with values:

      • RECEIVED

      • INVALID

      • CREATED

      • PENDING

      • APPROVED

      • REJECTED

      • ARCHIVED

2. Resource-Type Specific Document Types

The document API now supports entity-specific document types, allowing better categorization:

  • Natural Person Documents:

    • General-purpose documents: GENERAL, COMMUNICATION, MARKETING, TRAINING, etc.

    • Identity verification: IDENTIFICATION_CERTIFICATE

    • Residence proof: PROOF_OF_RESIDENCE

    • Special cases: BIRTH_CERTIFICATE, KYC

    • Other documents: OTHER

  • Legal Entity Documents:

    • Generic documents: KYC

    • Registry information: CURRENT_REGISTRY_EXTRACT, CHRONOLOGICAL_REGISTRY_EXTRACT

    • Ownership documents: SHAREHOLDER_LIST, TRANSPARENCY_REGISTER_EXTRACT

    • Organizational documents: PARTNERSHIP_AGREEMENT, STATUTE, BUSINESS_REGISTRATION

    • Tax documents: NON_ASSESSMENT_CERTIFICATE

  • Customer-specific Documents:

    • All customer types support: GENERAL, CONTRACTS, ONBOARDING, COMMUNICATION, MARKETING, TRAINING, OTHER

    • Natural person customers: additional KYC document types

  • Proxy-specific Documents:

    • Guardian: PROOF_OF_SINGLE_CUSTODY, PROOF_OF_CUSTODY

    • Liquidator: INSOLVENCY_ORDER

    • General proxy with death validity: INHERITANCE_LEGITIMATION

3. Changelog Integration

The document management system is now fully integrated with the changelog API:

  • Added document-related changelog types:

    • CUSTOMER_DOCUMENT

    • PROXY_DOCUMENT

    • NATURAL_PERSON_DOCUMENT

    • LEGAL_ENTITY_DOCUMENT

    • DOCUMENT (generic type)

These changes align the document management system with the overall entity-role architecture, providing more precise document categorization based on the associated entity type and improved tracking of document-related events throughout the system.

Benefits of the New Architecture

  1. Better Separation of Concerns:

    • Entity management and role management are clearly separated

    • Each API has a focused responsibility

  2. Improved Modularity:

    • Easier to add new entity types

    • Easier to add new role types

    • Better component isolation

  3. Enhanced Process Flows:

    • Clearer distinction between entity creation and role assignment

    • More intuitive API for complex operations

  4. Better Search and Filtering:

    • New parameters and options for entity filtering

    • Enhanced query capabilities

  5. Future Extensibility:

    • Architecture designed to scale with new entity types

    • Can accommodate new role types without structural changes

Migration Considerations

When migrating from the old API to the new structure:

  1. Update client code to use the appropriate entity or role endpoint

  2. Adjust to the new onboarding and offboarding processes

  3. Update webhook handlers to support the new notification endpoints

  4. Review entity status handling to accommodate the new, more specific status enums

  5. Update role management logic to work with the separated role APIs

Conclusion

The migration from customers.yaml to entities.yaml and roles.yaml represents a significant architectural improvement that brings greater flexibility, clarity, and maintainability to the API. The clearer separation of entities from roles enables more powerful business processes while simplifying the overall system architecture.

Last updated