Legal Entity Update Process

This document describes the overall process for updating existing legal entities on the platform, from initial data submission, through validation stages, to the final update of the legal entity record or handling of exceptions.

Overview

The Legal Entity Update Process ensures the integrity and compliance of legal entity data modifications by performing comprehensive validation procedures. This process maintains data quality standards, ensures regulatory compliance, and handles legal entity relationship updates efficiently across all platform operations.

Prerequisites

Partners need to:

  • Have an existing legal entity with appropriate status for updates (CREATED or ACTIVE)

  • Gather all required update information

  • Ensure proper authorization to update the legal entity data

Validation Types

The legal entity 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 LegalEntityUpdate, including:

  • Field length validation - Validates minimum and maximum character limits for updated fields

  • Format validation - Validates field formats using regex patterns for updated fields

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

  • Enum validation - Validates that enum fields contain only allowed values

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

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 legal entity updates.

Asynchronous validations include:

  • Checking if the externalId field is unique across partner

Business Process Flow

The update process follows a structured workflow:

  1. Legal Entity Retrieval - Existing legal entity is fetched and verified

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

  3. Command Event Publishing - Legal entity update command event is published

  4. Asynchronous Business Validation - Comprehensive verification and routing decisions

  5. Legal Entity Update - Official update in the system

  6. Exception Handling - Management of rejected or problematic cases

How to Call the Update Endpoint

The update request is performed by calling the endpoint:

PUT /entities/legal-entities/{legalEntityId}

Validation Framework

Data Quality Assurance

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

Initial Data Verification

  • Verifies legal entity exists and is accessible

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

  • Confirms proper partner authorization

Business Validation Steps (Asynchronous)

  1. Legal Entity Existence and Verification

    • Retrieves the existing legal entity by UUID

    • Verifies legal entity exists and belongs to the correct partner

    • Returns validation error if legal entity is not found or not accessible

  2. External ID Uniqueness Check

    • Checks if the externalId is unique across the partner

    • Returns validation error if externalId is already in use by another legal entity

  3. Legal Entity Data Update

    • Updates legal entity data both locally and globally

    • Applies changes to the database

    • Retrieves updated legal entity for verification

Business Outcomes

1. Data Validation Failure (Immediate Rejection)

When it occurs:

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

    • Invalid data formats

    • Invalid field values

Business Impact:

  • Legal entity 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

  • Check data formats for correctness

  • Resubmit the corrected legal entity update data

2. Asynchronous Validation Failure

When it occurs:

  • External ID is not unique across the partner

  • Legal entity not found or not accessible by partner

Business Impact:

  • Legal entity update is rejected

  • Partner receives detailed validation error notification via webhook/notification

  • Legal entity remains in its original state

Next Steps:

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

  • Resubmit legal entity update request after resolving validation issues

3. Successful Update

When it occurs:

  • All validations pass (both immediate and asynchronous)

Business Impact:

  • Legal entity is successfully updated in system

  • Partner receives success notification via webhook/notification

Business Rules

Update Eligibility

  • Legal entities can only be updated if they exist and are accessible by the partner

  • Partner must have proper authorization to update the legal entity

Data Update Rules

  • Update affects both local and global legal entity data

  • Changes are applied atomically

  • Legal entity status cannot be directly changed through the update endpoint

Last updated