Beneficial Owner Update Process

This document describes the overall process for updating existing beneficial owners on the platform, from initial data submission, through validation stages, to the final update of the beneficial owner's record or handling of exceptions.

Overview

The Beneficial Owner Update Process ensures the integrity and compliance of beneficial owner data modifications by performing comprehensive validation procedures. This process maintains data quality standards, ensures regulatory compliance, and handles person basic data updates efficiently across all platform operations. All beneficial owners are of type REAL_UBO_25. Note: AML/KYC compliance verification occurs separately during the beneficial owner onboarding process, not during the update process itself.

Prerequisites

Partners need to:

  • Have an existing beneficial owner with appropriate status for updates

  • Gather all required update information

  • Ensure proper authorization to update the beneficial owner data

Validation Types

The beneficial owner update 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 for BeneficialOwnerUpdate, including:

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

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

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

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

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

  • Nationalities validation - Ensures at least one nationality is provided when nationalities field is updated ( minItems: 1)

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 Update validation - Validates personal information format and structure when updating personal data

  • UBO Relationship validation - Validates uboRelationship consistency when provided. Valid values are:

    • 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

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

    • For DIRECTLY_HOLDING_25 or INDIRECTLY_HOLDING_25: either share or voting rights must be >= 25% (considering current and updated values)

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

  • Address validation - Validates address format and structure when mainAddress is provided

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 and compliance checks specific to beneficial owner updates.

Asynchronous validations include:

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

  • Geographic compliance checks - Validates updated addresses against whitelisted residencies

  • FATCA controlling person validation against legal entity FATCA classification

  • Existing beneficial owner retrieval and status verification

Business Process Flow

The update process follows a structured workflow:

  1. Beneficial Owner Retrieval - Existing beneficial owner is fetched and verified

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

  3. Command Event Publishing - Beneficial owner update command event is published

  4. Asynchronous Business Validation - Comprehensive verification and routing decisions

  5. Person Basic Data Update - Updates existing person basic data if provided in update request

  6. Beneficial Owner Update - Official update in the system

  7. Exception Handling - Management of rejected or problematic cases

How to Call the Update Endpoint

The update request is performed by calling the endpoint:

PATCH /entities/beneficial-owners/{beneficialOwnerId}

Available Update Fields

The following fields can be updated through the beneficial owner update endpoint:

  • Personal Information: firstName, lastName, birthDay, birthPlace, birthCountry

  • Contact Information: mainAddress, nationalities

  • Tax Information: taxDetails, isUsNationality

  • Ownership Information: uboRelationship, share, votingRights

  • FATCA Information: fatcaControllingPerson

Note: The beneficial owner type (boType) cannot be updated as all beneficial owners are of type REAL_UBO_25.

Validation Framework

Data Quality Assurance

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

Initial Data Verification

  • Verifies beneficial owner exists and is accessible

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

  • Confirms proper partner authorization

  • Validates legal entity exists and is accessible

Business Validation Steps (Asynchronous)

  1. Beneficial Owner Existence Validation

    • Retrieves the existing beneficial owner by UUID

    • Verifies beneficial owner exists and belongs to the correct partner

    • Returns validation error if beneficial owner is not found or not accessible

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

  3. Beneficial Owner Update Data Validation

    • Validates beneficial owner update data using business rules

    • Checks field formats and data consistency

    • Ensures UBO relationship consistency with share and voting rights values (current and updated)

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

  4. Geographic Compliance Validation

    • Retrieves whitelisted residencies

    • Validates updated beneficial owner addresses against whitelisted countries (when mainAddress is provided)

    • Returns validation error if updated address is not in whitelisted residencies

  5. FATCA Validation

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

    • Ensures compliance with FATCA reporting requirements

  6. Person Basic Data Update Processing

    • If personal data fields are provided in update: Updates existing person basic data using the global ID from current beneficial owner

    • Person basic data is updated by global ID ensuring consistency across all references to this person

Business Outcomes

1. Data Validation Failure (Immediate Rejection)

When it occurs:

  • Beneficial owner not found or not accessible by partner

  • Incomplete or incorrectly formatted beneficial owner update data. This includes checks for:

    • Invalid formats for personal basic data fields (e.g., first name, last name, birthdate, birthplace, birth country)

    • Invalid formats for contact data (e.g., address, nationalities)

    • Incorrect data formats for updated fields

  • Invalid UBO relationship and share/voting rights combination:

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

    • Invalid UBO relationship value

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

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

Business Impact:

  • Beneficial owner update is immediately rejected

  • Partner receives validation error notification

  • Partner must correct the submitted data and resubmit

Next Steps:

  • Review and correct the submitted update data

  • Ensure all updated fields are properly formatted

  • Verify UBO relationship is consistent with share and voting rights values (considering both current and updated values)

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

  • Resubmit the corrected beneficial owner update data

2. Asynchronous Validation Failure

When it occurs:

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

  • Updated address is not in whitelisted residencies

  • Specific business rule violations discovered during comprehensive validation:

    • FATCA Classification Inconsistency: Setting FatcaControllingPerson to true when legal entity's FATCA classification is not PASSIVE_NFE, or setting it to false when classification is PASSIVE_NFE

    • UBO Relationship vs Share/Voting Rights Inconsistency: Updating UBO relationship or share/voting rights values that violate the relationship-based validation rules

    • Person Basic Data Validation Failures: Updated person basic data doesn't meet format, structure, or business logic requirements

Business Impact:

  • Beneficial owner update is halted

  • Partner receives error notification via webhook/notification

  • Manual intervention may be required

Next Steps:

  • Address the specific validation failure

  • Ensure legal entity has appropriate status

  • Verify updated address compliance with geographic restrictions

  • Correct FATCA-related issues if applicable

  • Ensure UBO relationship consistency with share and voting rights values

3. Successful Update

When it occurs:

  • All validations pass (both immediate and asynchronous)

  • Legal entity status is appropriate

  • No geographic compliance issues with updated data

  • Person basic data is successfully updated (if provided)

Business Impact:

  • Beneficial owner is successfully updated in system

  • Person basic data is updated using global ID (if personal data fields were provided in update)

  • Partner receives success notification via webhook/notification

Business Rules

Legal Entity Requirements

  • Beneficial owners can only be updated 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 are of type REAL_UBO_25 - the beneficial owner type cannot be updated

  • UBO relationship can be updated and must follow the validation rules based on share and voting rights values

Share and Voting Rights Validation Rules

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

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

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

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

  • UBO Relationship-based validation:

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

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

Geographic Rules

  • Updated addresses must be in whitelisted residencies (when mainAddress is provided)

  • Non-whitelisted locations cause validation failure

FATCA Rules

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

  • Compliance with FATCA reporting requirements is enforced

Person Basic Data Update Management

  • When personal data fields are provided: Existing person basic data is updated using the global ID from current beneficial owner

  • When personal data fields are not provided: Person basic data remains unchanged

  • Person basic data updates affect all references to this person globally

Last updated