Legal Representative Create Process

This document describes the overall process for creating new legal representatives on the platform, from initial data submission, through validation and review stages, to the final creation of the legal representative's record or handling of exceptions.

Overview

The Legal Representative Creation Process ensures the integrity and compliance of legal representative data by performing comprehensive validation and review procedures. This process protects against duplicate creations, maintains data quality standards, and ensures regulatory compliance across all platform operations. Legal representatives are individuals who are authorized to act on behalf of legal entities and represent them in legal and business matters

Prerequisites

Partners need to gather all required legal representative information and ensure the associated legal entity exists before initiating the Legal Representative creation process.

Validation Types

The legal representative creation process includes two types of validations:

1. Immediate Static Validations (Synchronous)

These validations are performed immediately when calling the endpoint and return errors directly to the user without delay. They validate data format, structure, and basic business rules to ensure data quality and completeness.

Static validations include:

API Layer Validations (OpenAPI Schema):

All field-level validations defined in the OpenAPI schema are automatically enforced, including:

  • Field requirements validation - Ensures all required fields are provided (e.g., firstName, lastName, birthDay, birthPlace, birthCountry, taxDetails, isUsNationality, nationalities, function, soleSignatureAuthorized, fatcaControllingPerson)

  • Field length validation - Validates minimum and maximum character limits (e.g., firstName max 255 characters, lastName max 255 characters, birthPlace max 255 characters)

  • Format validation - Validates field formats using regex patterns (e.g., firstName pattern "^\S+( \S+)*$")

  • Data type validation - Ensures correct data types for all fields

  • Function validation - Validates legal representative function against allowed enum values

For detailed field specifications, length limits, and regex patterns, refer to the OpenAPI schema definitions in reference/entities.yaml

Business Logic Validations:

  • Person Basic Data validation - Validates personal information format and structure

  • FATCA Controlling Person validation - Ensures taxDetails is provided when fatcaControllingPerson = TRUE

  • Function validation - Validates legal representative function against allowed values

  • US Citizenship Relationship validation - Validates consistency between US nationality flags and nationality list

  • Tax Details validation - Validates tax residency information format and requirements

  • Address validation - Validates address format and structure (main address is required)

  • Sole Signature Authorization validation - Validates boolean value for signature authorization

2. Asynchronous Business Validations

These validations are performed asynchronously after the endpoint returns a successful response. Results are delivered via webhooks or notification systems. They include complex business logic, duplicate detection, and compliance checks specific to legal representative creation.

Asynchronous validations include:

  • Global duplicate detection across the entire system for person basic data

  • Restricted data changes validation

  • Matching with existing global records

  • Legal entity status validation (must be ACTIVE or CREATED)

  • Geographic compliance checks - Validates addresses against whitelisted residencies

  • FATCA controlling person validation against legal entity FATCA classification

Business Process Flow

The creation process follows a structured workflow:

  1. Immediate Static Validation - Format and structure verification (synchronous)

  2. Command Event Publishing - Legal representative create command event is published

  3. Data Storage - Legal representative data is stored with RECEIVED status

  4. Asynchronous Business Validation & Review - Comprehensive verification and routing decisions

  5. Legal Representative Creation - Official creation in the system or routing to review

  6. Exception Handling - Management of rejected or problematic cases

How to Call the Create Endpoint

The create request is performed by calling the endpoint:

POST /entities/{legalEntityId}/legal-representatives

Validation Framework

Data Quality Assurance

The validation process performs thorough checks to ensure data accuracy and completeness:

Initial Data Verification

  • Ensures all required legal representative information is provided

  • Validates data format and completeness using static validations (immediate)

  • Confirms proper partner authorization

  • Validates legal entity exists and is accessible

Business Validation Steps (Asynchronous)

  1. Legal Entity Status Validation

    • Retrieves the associated legal entity

    • Verifies legal entity status is ACTIVE or CREATED

    • Returns validation error if legal entity has inappropriate status

  2. Legal Representative Data Validation

    • Validates legal representative data using business rules

    • Checks required fields and data formats

    • Ensures FATCA controlling person requirements are met

    • Validates function against allowed values

    • Ensures taxDetails is provided when fatcaControllingPerson = TRUE

  3. Geographic Compliance Validation

    • Retrieves whitelisted residencies

    • Validates legal representative addresses against whitelisted countries

    • Returns validation error if address is not in whitelisted residencies

  4. FATCA Validation

    • Validates FATCA controlling person status against legal entity's FATCA classification

    • Ensures compliance with FATCA reporting requirements

    • Validates tax details when fatcaControllingPerson = TRUE

  5. Global Duplicate Detection

    • Searches for matching person basic data across the system's global database. This search uses core identifying attributes of a person.

    • Compares with existing records system-wide to identify potential exact matches (duplicates).

    • Finds potential duplicates regardless of the originating partner or system source.

    • Identifies similar persons by basic data: If an exact match isn't found, the system performs a broader search for individuals with similar core personal identifiers. "Basic data" in this context refers to fundamental personal details such as first name, last name, date of birth, birthplace and birth country or tax details. This wider search helps flag cases where a person might already exist in the system with slightly different or incomplete information (e.g., a slightly different spelling).

  6. Restricted Data Changes Check

    • Compares critical personal information with existing global records if a potential match (based on basic data) is found in the system's global database.

    • Generates a summary of differences for review: If the new information for an apparently existing person shows changes in specific, pre-defined critical fields, these differences are highlighted for a manual compliance review.

    • Flags data conflicts requiring manual review.

    • Restricted (Critical) Data: The system maintains a list of personal data fields considered critical for identity and compliance. When a new legal representative is being created and a corresponding global person record already exists, the system compares these critical fields. This includes core identity details (like name, date of birth) and other sensitive information (like tax identifiers or key contact details, e.g., tax details modifications). If the incoming data suggests a modification to these existing global details, it is flagged for review.

Business Outcomes

1. Data Validation Failure (Immediate Rejection)

When it occurs:

  • Incomplete or incorrectly formatted legal representative data. This includes checks for:

    • Validity and completeness of personal basic data (e.g., first name, last name, birthdate, birthplace, birth country, tax details)

    • Validity and completeness of contact data (e.g., address, nationalities)

    • Presence of all other required fields

    • Correct data formats for all fields

  • Missing or invalid legal representative function

  • Missing taxDetails when fatcaControllingPerson = TRUE

  • Invalid boolean values for soleSignatureAuthorized or fatcaControllingPerson

Business Impact:

  • Legal representative creation is immediately rejected

  • Partner receives validation error notification

  • Partner must correct the submitted data and resubmit

Next Steps:

  • Review and correct the submitted data

  • Ensure all required fields are complete

  • Verify legal representative function is valid

  • Ensure taxDetails is provided when fatcaControllingPerson = TRUE

  • Verify boolean fields have correct values

  • Resubmit the corrected legal representative data

2. Asynchronous Validation Failure

When it occurs:

  • Legal entity has inappropriate status (not ACTIVE or CREATED)

  • Address is not in whitelisted residencies

  • FATCA controlling person validation fails

  • Business rule violations discovered during comprehensive validation

Business Impact:

  • Legal representative creation is rejected

  • Partner receives detailed validation error notification via webhook/notification

  • No legal representative record is created in the system

Next Steps:

  • Address the specific validation failure based on error details received in webhook

  • Ensure legal entity has appropriate status (ACTIVE or CREATED)

  • Update addresses to whitelisted residencies if needed

  • Resolve FATCA compliance issues

  • Provide taxDetails when fatcaControllingPerson = TRUE

  • Resubmit legal representative creation request after resolving validation issues

3. Manual Review Required (Asynchronous Decision)

When it occurs:

  • Person basic data found in global database: An existing record matching core identifying attributes (like first name, last name, date of birth, birthplace and birth country or tax details) of the incoming legal representative is found in the system's central database.

  • Matching data diff patch generated: Changes are detected in critical personal or contact information when comparing the incoming data against an existing global record for that individual.

  • Similar persons found by basic data: Even if no exact match is found, the system identifies existing global records with highly similar core identifying attributes, suggesting a potential duplicate.

  • Restricted data changes detected: The process identifies discrepancies in pre-defined critical data fields between the incoming legal representative information and an existing global record for that individual.

Business Impact:

  • Legal representative status is set to "Under Review"

  • Admin is notified for manual verification

  • Legal representative creation is temporarily suspended

  • Partner receives notification about review status via webhook/notification

Review Process:

  • Admin task process is initiated

  • Legal representative set to REVIEW

  • Admin task data includes difference patch and similar persons

  • Decision callback returns to the legal representative create process

Admin Task Reasons:

  • MATCHING_SIMILARITIES - Created when no exact match is found but similar records are discovered in the global database. This task type handles cases where potential duplicates exist based on similar core identifying attributes.

    • Available Admin Decisions:

      • MATCH - Admin confirms that the legal representative should be matched with an existing global record. Admin must provide the global_id of the existing record to match with.

      • NOT_MATCH - Admin confirms that the legal representative is unique and should be created as a new record without matching to any existing global record.

  • LEGAL_REPRESENTATIVE_CREATE - Created when an exact match is found and changes are detected in critical data fields. This task type handles cases where restricted data modifications require manual review and approval.

    • Available Admin Decisions:

      • APPROVE - Admin approves the critical data changes. The global record will be updated with the new information and the legal representative will be successfully created.

      • REJECT - Admin rejects the critical data changes. The legal representative creation will be rejected and no changes will be made to the global record.

4. Automatic Approval (Direct Creation)

When it occurs:

  • All validations pass (both immediate and asynchronous)

  • No matching data diff patch generated

  • No similar persons found

  • Legal representative data is valid

Business Impact:

  • Legal representative will be successfully created in system

  • Legal representative status will be set to CREATED

  • Partner receives success notification via webhook/notification

Business Rules

Legal Entity Requirements

  • Legal representatives can only be created for legal entities

  • Legal entity must have status ACTIVE or CREATED

  • Legal entity must be accessible by the partner

Legal Representative Function Rules

  • Function: Must be a valid value from LegalRepresentativeFunctionEnum

  • Function determines the legal authority and responsibilities of the representative

  • Each legal entity can have multiple legal representatives with different functions

FATCA Rules

  • FATCA Controlling Person: Boolean flag indicating if person is a controlling person under FATCA

  • Tax Details Requirement: taxDetails must be provided when fatcaControllingPerson = TRUE

  • FATCA controlling person status must be consistent with legal entity's FATCA classification

  • Compliance with FATCA reporting requirements is enforced

Signature Authorization Rules

  • Sole Signature Authorized: Boolean flag indicating whether the legal representative is authorized to represent the company individually

  • This determines the legal representative's authority to act independently on behalf of the legal entity

Geographic Rules

  • Addresses must be in whitelisted residencies

  • Non-whitelisted locations cause validation failure

Person Basic Data Management

  • Global person basic data is reused when existing person is found

  • New person basic data is created when person doesn't exist globally

  • Person basic data updates are performed when legal representative is linked to existing global person

Integration with Legal Entity Customer Onboarding

Automatic FICTIVE_UBO Creation from Legal Representatives

During the Legal Entity Customer (LEC) onboarding process, the system performs automatic beneficial owner management to ensure regulatory compliance:

When it occurs:

  • Legal Entity Customer is proceeding through the onboarding process

  • System detects that no REAL_UBO_25 beneficial owners with CREATED status exist for the legal entity

What happens:

  1. Existing Beneficial Owner Cleanup: All existing beneficial owners are removed from the legal entity

  2. Legal Representative Retrieval: System retrieves all ACTIVE legal representatives associated with the legal entity

  3. Automatic FICTIVE_UBO Creation: Each legal representative is automatically converted into a FICTIVE_UBO beneficial owner with:

    • FICTIVE_UBO type designation

    • 0% share allocation

    • PENDING status

    • All personal data copied from the legal representative record

Business Impact:

  • Ensures continuous regulatory compliance during onboarding

  • Eliminates manual intervention for FICTIVE_UBO creation

  • Maintains proper beneficial ownership records even when no person holds 25% or more shares

  • Streamlines the onboarding process for legal entities without significant individual shareholders

Note: This automatic process only occurs during the onboarding workflow and does not affect the manual legal representative creation process described in this document.

Last updated