Beneficial Owner Create Process

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

Overview

The Beneficial Owner Creation Process ensures the integrity and compliance of beneficial owner 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. Beneficial owners are individuals who hold shares or control rights in legal entities. All beneficial owners created through this process are of type REAL_UBO_25. Note: AML/KYC compliance verification occurs separately during the beneficial owner onboarding process, not during the creation process itself.

Prerequisites

Partners need to gather all required beneficial owner information and ensure the associated legal entity exists before initiating the Beneficial Owner creation process.

Validation Types

The beneficial owner 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, uboRelationship, share, votingRights)

  • 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

  • Share validation - Validates share percentage (0-100%, multiple of 0.01, exclusive minimum > 0)

  • Voting rights validation - Validates voting rights percentage (0-100%, multiple of 0.01, exclusive minimum > 0)

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

  • UBO Relationship validation - Ensures uboRelationship is provided (mandatory field). Valid values are:

    • DIRECTLY_HOLDING_25 - person directly holds shares in the capital and voting rights of a company

    • INDIRECTLY_HOLDING_25 - person indirectly holds shares in the capital and voting rights through intermediary entities or trust arrangements

    • DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL - person exercises control over the company in any other way, such as through voting agreements, special rights, or trust relationships, even without (or with only minor) direct or indirect shareholdings

  • Share and Voting Rights vs UBO Relationship consistency - Validates share and voting rights based on UBO relationship:

    • For DIRECTLY_HOLDING_25 or INDIRECTLY_HOLDING_25: either share or voting rights must be >= 25%

    • For DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL: no minimum requirement for share or voting rights 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)

  • Voting rights validation - Validates voting rights are provided and within valid range

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 beneficial owner 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 - Beneficial owner create command event is published

  3. Data Storage - Beneficial owner data is stored with RECEIVED status

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

  5. Beneficial Owner 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}/beneficial-owners

Validation Framework

Data Quality Assurance

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

Initial Data Verification

  • Ensures all required beneficial owner 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. Beneficial Owner Data Validation

    • Validates beneficial owner data using business rules

    • Checks required fields and data formats

    • Ensures UBO relationship consistency with share and voting rights values

    • Validates share and voting rights percentages based on UBO relationship type

  3. Geographic Compliance Validation

    • Retrieves whitelisted residencies

    • Validates beneficial owner 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

  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 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 beneficial owner 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 beneficial owner 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 including votingRights and uboRelationship

    • Correct data formats for all fields

  • Invalid UBO relationship and share/voting rights combination:

    • For DIRECTLY_HOLDING_25 or INDIRECTLY_HOLDING_25: neither share nor voting rights are >= 25%

    • Missing required UBO relationship

  • Share percentage validation errors (not between 0-100%, not multiple of 0.01)

  • Voting rights validation errors (not between 0-100%, not multiple of 0.01)

Business Impact:

  • Beneficial owner 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 including votingRights and uboRelationship

  • Verify UBO relationship is consistent with share and voting rights values

  • For DIRECTLY_HOLDING_25 or INDIRECTLY_HOLDING_25 relationships, ensure either share or voting rights >= 25%

  • Resubmit the corrected beneficial owner 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:

  • Beneficial owner creation is rejected

  • Partner receives detailed validation error notification via webhook/notification

  • No beneficial owner 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

  • Resubmit beneficial owner 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 beneficial owner 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 beneficial owner information and an existing global record for that individual.

Business Impact:

  • Beneficial owner status is set to "Under Review"

  • Admin is notified for manual verification

  • Beneficial owner creation is temporarily suspended

  • Partner receives notification about review status via webhook/notification

Review Process:

  • Admin task process is initiated

  • Beneficial owner set to REVIEW

  • Admin task data includes difference patch and similar persons

  • Decision callback returns to the beneficial owner 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 beneficial owner 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 beneficial owner is unique and should be created as a new record without matching to any existing global record.

  • BENEFICIAL_OWNER_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 beneficial owner will be successfully created.

      • REJECT - Admin rejects the critical data changes. The beneficial owner 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

  • Beneficial owner data is valid

Business Impact:

  • Beneficial owner will be successfully created in system with type REAL_UBO_25

  • Beneficial owner status will be set to CREATED

  • Partner receives success notification via webhook/notification

Business Rules

Legal Entity Requirements

  • Beneficial owners can only be created for legal entities

  • Legal entity must have status ACTIVE or CREATED

  • Legal entity must be accessible by the partner

Beneficial Owner Type Rules

  • All beneficial owners created are of type REAL_UBO_25 - the boType parameter is no longer used

  • UBO relationship must be provided (mandatory field) with one of the following values:

    • DIRECTLY_HOLDING_25 - person directly holds shares in the capital or voting rights of a company

    • INDIRECTLY_HOLDING_25 - person indirectly holds shares in the capital or voting rights through intermediary entities or trust arrangements

    • DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL - person exercises control over the company in any other way, such as through voting agreements, special rights, or trust relationships, even without (or with only minor) direct or indirect shareholdings

Important Note: During the Legal Entity Customer (LEC) onboarding process, if no REAL_UBO_25 beneficial owners with CREATED status exist, the system automatically creates FICTIVE_UBO beneficial owners based on the legal representatives associated with the legal entity. This ensures regulatory compliance by maintaining proper beneficial ownership records even when no person holds 25% or more shares.

Share and Voting Rights Validation Rules

  • Share must be greater than 0% and not exceed 100%

  • Share must be specified with precision of 0.01 (two decimal places)

  • Voting rights must be greater than 0% and not exceed 100%

  • Voting rights must be specified with precision of 0.01 (two decimal places)

  • Voting rights are required for all beneficial owners

  • UBO Relationship-based validation:

    • For DIRECTLY_HOLDING_25 or INDIRECTLY_HOLDING_25: either share or voting rights must be >= 25%

    • For DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL: no minimum requirement for share or voting rights values

Geographic Rules

  • Addresses must be in whitelisted residencies

  • Non-whitelisted locations cause validation failure

FATCA Rules

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

  • Compliance with FATCA reporting requirements is enforced

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 beneficial owner is linked to existing global person

Beneficial Owner Status Values

The following status values are available for beneficial owners throughout their lifecycle:

  • CREATED - Beneficial owner successfully created and validated

  • ACTIVE - Beneficial owner is active in the system

  • INACTIVE - Beneficial owner has been deactivated

  • RECEIVED - Initial status when beneficial owner data is received for processing

  • INVALID - Beneficial owner data failed validation

  • REJECTED - Beneficial owner creation was rejected

  • REVIEW - Beneficial owner is under manual review

  • PENDING - Beneficial owner is awaiting further processing

  • SUSPENDED_COMPLIANCE - Beneficial owner suspended due to compliance issues

Integration with Legal Entity Customer Onboarding

Automatic FICTIVE_UBO Creation

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

    • 0% voting rights 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 beneficial owner creation process described in this document. Manual creation always produces REAL_UBO_25 type beneficial owners.

Last updated