tradevest.ai

Legal Entity Update Process

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

Overview

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

Prerequisites

Partners need to:

  • Have created a Legal Entity with CREATED or ACTIVE status

  • Upload necessary supporting documents before initiating updates for certain fields (only for legal entity in ACTIVE status)

  • Provide appropriate document references (documentIds) for specific types of updates (only for legal entity in ACTIVE status)

  • Ensure that vendor was not used for legal entity creation if updating vendor-provided fields

Required Documents

For specific types of Legal Entity data updates, providing an appropriate supporting document is mandatory for entity in status ACTIVE:

Document Requirements by Field:

  • legalName - requires documents: CURRENT_REGISTRY_EXTRACT, SHAREHOLDER_LIST, TRANSPARENCY_REGISTER_EXTRACT

  • legalForm - requires documents based on legal form type (see Legal Form Document Requirements below)

  • mainAddress, correspondenceAddress, invoiceAddress - requires document: CURRENT_REGISTRY_EXTRACT

Legal Form Document Requirements:

When updating legalForm, the following documents are required based on the legal form type:

  • LIMITED_LIABILITY_COMPANY - CURRENT_REGISTRY_EXTRACT, SHAREHOLDER_LIST

  • PUBLIC_LIMITED_COMPANY - CURRENT_REGISTRY_EXTRACT, TRANSPARENCY_REGISTER_EXTRACT

  • FOUNDATION - CURRENT_REGISTRY_EXTRACT, STATUTE

  • ASSOCIATION - STATUTE

  • REGISTERED_BUSINESSMAN - CURRENT_REGISTRY_EXTRACT

  • LIMITED_PARTNERSHIP - CURRENT_REGISTRY_EXTRACT, TRANSPARENCY_REGISTER_EXTRACT

  • GENERAL_PARTNERSHIP - CURRENT_REGISTRY_EXTRACT, SHAREHOLDER_LIST, TRANSPARENCY_REGISTER_EXTRACT

  • LIMITED_LIABILITY_COMPANY_AND_LIMITED_PARTNERSHIP - CURRENT_REGISTRY_EXTRACT, SHAREHOLDER_LIST, TRANSPARENCY_REGISTER_EXTRACT

  • PARTNERSHIP - PARTNERSHIP_AGREEMENT

The document identifiers (documentIds) must be provided in the update request for the above-mentioned fields for legal entity in status ACTIVE.

Available Update Fields

For legal entities with ACTIVE status, the following fields can be updated:

  • legalName

  • legalForm

  • naceSectors

  • taxNumber

  • vatId

  • isListed

  • listedAt

  • legalEntityIdentifier (LEI)

  • purpose

  • fatcaCrsDeclaration

  • mainAddress, correspondenceAddress, invoiceAddress

  • averageProfit, averageRevenue, liquidAssets

  • lastAnnualFinancialStatement

  • externalId

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

Business Logic Static Validations:

  • Document ID requirement validation - Validates that documentIds are provided for fields that require it ( legalName, legalForm, addresses) only for legal entity in status ACTIVE. For CREATED status, documents are not required in static validation.

  • Address validation - Validates address format and structure if provided:

    • Zip code validation - Validates zip code length (minimum 3, maximum 10 characters)

    • US address restriction (CREATED status only) - For legal entities in CREATED status, US addresses are not allowed and will return validation error. For ACTIVE status, US addresses are allowed and will trigger compliance review.

    • Foreign tax residency requirement - When main address country is not DE, fatcaCrsDeclaration.isForeignTaxResidency must be set to TRUE. Returns validation error if not met.

  • FATCA/CRS declaration validation - Validates FATCA/CRS declaration structure and basic rules:

    • ACTIVE_NFE classification - If fatcaClassification is ACTIVE_NFE, activeNfeType must be provided. Returns validation error if missing.

    • Sanctioned countries restriction (CREATED status only) - For legal entities in CREATED status, isSanctionedCountries=true is not allowed and will return validation error. For ACTIVE status, this value is allowed and will trigger compliance review.

    • NON_PROFIT_ORGANISATION restriction (CREATED status only) - For legal entities in CREATED status, activeNfeType=NON_PROFIT_ORGANISATION is not allowed and will return validation error. For ACTIVE status, this value is allowed and will trigger compliance review.

  • NACE Sectors validation - Validates NACE sector codes structure if provided:

    • Code validation - Validates that NACE sector code is not empty

    • Section validation - Validates NACE sector section format (if provided)

    • Duplicate validation - Validates that there are no duplicate NACE sectors

    • Note: Banned sectors validation is not performed in static validations. It is handled asynchronously in business validations.

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:

  • Legal Entity status validation - Validates legal entity status allows the specific type of update

  • Document existence and type validation - Verifies provided documentIds reference existing documents of correct type

  • LEI validation - Validates and retrieves LEI data from vendor API when legalEntityIdentifier is updated

  • NACE sector business validity - Validates NACE sectors against valid/banned sector lists and normalizes them

  • Geographic compliance checks - Validates address changes against whitelisted residencies

  • FATCA/CRS compliance validation - Validates FATCA/CRS declaration changes and related requirements

  • External ID uniqueness check - Checks if the externalId is unique across partner

How to Call the Update Endpoint

The update request is performed by calling the endpoint:

PUT /entities/legal-entities/{legalEntityId}

The request structure should contain a LegalEntityUpdateCommandData object:

{
  "legalEntityUpdate": {
    // data to be updated
  },
  "documentIds": ["uuid-of-document-1", "uuid-of-document-2"]
  // required for specific fields when legal entity is in ACTIVE status
}

Validation Framework

Data Quality Assurance

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

Initial Static Verification (Synchronous)

  • Ensures all required update information is provided and properly formatted

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

  • Confirms proper partner authorization and legal entity existence

  • Validates document ID requirements for specific fields (ACTIVE status only)

  • Performs address format and structure validations

  • Performs FATCA/CRS declaration structure validations

  • Performs NACE sectors structure validations

Business Validation Steps (Asynchronous)

  1. Legal Entity Status Validation

    • Validates that legal entity has CREATED or ACTIVE status

    • Only legal entities with CREATED or ACTIVE status can be updated

    • Returns validation error if legal entity does not have CREATED or ACTIVE status

  2. Requestor ID Validation

    • Validates requestor ID authorization for legal entity update (if provided)

    • Returns validation error if requestor is not authorized

  3. Vendor Fields Restriction Validation

    • Checks if vendor was used for legal entity creation

    • If vendor was used, validates that vendor-provided fields are not being updated

    • Vendor-provided fields: legalName, legalForm, naceSectors, taxNumber, vatId, isListed, listedAt, legalEntityIdentifier, purpose, fatcaCrsDeclaration

    • Returns validation error if vendor-provided fields are updated when vendor was used

  4. LEI Validation

    • If legalEntityIdentifier is being updated, validates LEI through vendor API

    • Retrieves LEI data (status, validUntil) from vendor API

    • Validates LEI format and structure

    • Returns validation error if LEI is invalid or not found

  5. NACE Sectors Validation

    • Gets valid NACE sectors for legal entities

    • Validates and normalizes provided NACE sector codes

    • Checks if each declared sector is on the valid list

    • For CREATED status: validates against banned sectors list

    • For ACTIVE status: allows banned sectors (these values pass validation but will trigger compliance review - see Review Detection Mechanism below)

    • Returns validation error if any sector is invalid (for CREATED status)

  6. Document Validation (ACTIVE status only)

    • Retrieves all documents associated with the legal entity

    • Validates that provided documentIds exist and reference correct document types

    • Ensures document types match requirements for specific field updates

    • Validates that all required document types are present in provided documentIds

    • Returns validation error if documents don't exist or have wrong type

  7. Geographic Compliance Validation

    • Validates address changes against whitelisted residencies

    • Validates isForeignTaxResidency requirement when main address country is not DE

    • For ACTIVE status: allows prohibited countries and US addresses (these values pass validation but will trigger compliance review - see Review Detection Mechanism below)

  8. FATCA/CRS Validation

    • Validates FATCA/CRS declaration structure and completeness

    • For ACTIVE_NFE classification: validates that activeNfeType is provided

    • For PASSIVE_NFE classification: validates that all Legal Representatives and Beneficial Owners have complete tax information (taxResidencies and taxIds)

    • Validates isForeignTaxResidency requirement when main address country is not DE

    • For ACTIVE status: allows sanctionedCountries=TRUE and activeNfeType=NON_PROFIT_ORGANISATION (these values pass validation but will trigger compliance review - see Review Detection Mechanism below)

  9. KYC Screening & Verification (ACTIVE status only)

    • External provider data validation - Legal entity data with proposed changes (preview) is sent to external KYC/AML screening services for verification before the actual update is applied

    • Data authenticity verification - Validates the accuracy and legitimacy of legal entity information against compliance databases

    • Compliance screening - Checks proposed changes against regulatory watchlist and sanctions databases

    • Risk assessment - Evaluates potential compliance risks associated with the data changes

    • Verification outcomes: Valid (automatic approval and update proceeds), Manual Review Required, Repeat KYC, or Rejected

Review Detection Mechanism

After all validations pass, the system analyzes the proposed changes to determine if manual review is required. This mechanism operates differently based on legal entity status:

Legal Entity in status CREATED:

  • No review requirements - All changes pass validation and proceed directly to update

  • No admin tasks are created regardless of which fields are being updated

Legal Entity in status ACTIVE:

  • Analyzes changes - Compares proposed changes with existing legal entity data to identify modifications in critical compliance fields

  • Detects review requirements - Checks if changes involve fields that require manual review based on:

    • Results from Geographic Compliance Validation (prohibited countries, US addresses)

    • Results from NACE Sectors Validation (banned sectors)

    • Results from FATCA/CRS Validation (sanctionedCountries=TRUE, activeNfeType=NON_PROFIT_ORGANISATION)

    • Direct updates to legalName or legalForm fields

  • Generates diff patch - Creates a summary of differences showing exactly what would change, focusing only on fields that require review

  • Determines review type - Classifies changes as requiring either:

    • Regular review (LEGAL_ENTITY_UPDATE reason) - for legalName or legalForm changes

    • Compliance review (COMPLIANCE_REVIEW reason) - for compliance-related changes (addresses, NACE sectors, FATCA/CRS flags)

  • Creates admin task - If restricted changes are detected, legal entity status changes to REVIEW and admin task is created with appropriate reason and diff patch

Note: Specific fields and conditions that trigger review are documented in the "Review Requirements" section below.

Business Process Flow

The update process follows a structured workflow:

  1. Immediate Static Validation - Format, structure, and basic business rule verification (synchronous)

  2. Legal Entity Retrieval - Fetch existing legal entity data and validate update eligibility

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

  4. KYC Screening & Verification - External provider validation of data authenticity and compliance (Legal Entity in status ACTIVE only)

  5. Legal Entity Update - Official update in the system or routing to review

  6. Exception Handling - Management of rejected or problematic cases

Process Flow Details

Flow for Legal Entity in CREATED Status:

  1. Validate - Performs all validations except document requirements and KYC check

  2. Update - Directly updates legal entity data (no review or KYC required)

Flow for Legal Entity in ACTIVE Status (No Review Required):

  1. Validate - Performs all validations including document requirements

  2. KycCheck - Sends legal entity to external KYC provider for verification

  3. KycResult - Processes KYC verification result

    • If valid → proceed to Update

    • If manual review required → create admin task with KYC_SUSPICIONS reason

    • If repeat KYC → proceed to RepeatKycVerification

  4. Update - Updates legal entity data

Flow for Legal Entity in ACTIVE Status (Review Required):

  1. Validate - Performs all validations

    • If review needed → changes status to REVIEW and creates admin task

    • Waits for admin decision callback

  2. ValidationProceed - Processes admin decision

    • If APPROVED → rollback status to previous, proceed to KycCheck

    • If REJECTED_ENTITY → stop update process

    • If APPROVE_AND_SUSPEND_GLOBALLY → rollback status, suspend globally, proceed to KycCheck

    • If status was CREATED → skip KYC and proceed directly to Update

  3. KycCheck - Sends legal entity to external KYC provider for verification (if status was ACTIVE)

  4. KycResult - Processes KYC verification result

    • If valid → proceed to Update

    • If manual review required → create admin task with KYC_SUSPICIONS reason

    • If repeat KYC → proceed to RepeatKycVerification

  5. Update - Updates legal entity data

Business Outcomes

1. Data Validation Failure (Immediate Rejection)

When it occurs:

  • Incomplete or incorrectly formatted legal entity update data

  • Missing required documentIds for fields that require documentation (ACTIVE status only)

  • Legal entity not found or does not have CREATED or ACTIVE status

  • Invalid NACE sector codes structure (empty code, invalid section format, duplicates)

  • US addresses in legal entities with CREATED status (allowed for ACTIVE status, triggers compliance review)

  • isForeignTaxResidency not set to TRUE when main address country is not DE

  • FATCA/CRS validation failures:

    • Missing activeNfeType when fatcaClassification is ACTIVE_NFE

    • isSanctionedCountries=true for legal entities in CREATED status (allowed for ACTIVE status, triggers compliance review)

    • activeNfeType=NON_PROFIT_ORGANISATION for legal entities in CREATED status (allowed for ACTIVE status, triggers compliance review)

  • Note: Vendor-provided fields restriction, LEI validation, document existence/type validation, banned NACE sectors validation, and FATCA/CRS PASSIVE_NFE tax information validation are performed asynchronously in business validations, not in static validations.

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

  • Ensure all required document IDs are provided (for ACTIVE status only)

  • Verify NACE sectors structure (code, section format, no duplicates)

  • Verify address format (zip code length 3-10 characters)

  • For CREATED status: ensure no US addresses, no isSanctionedCountries=true, no activeNfeType=NON_PROFIT_ORGANISATION

  • For ACTIVE status: US addresses and compliance flags are allowed but will trigger compliance review

  • Ensure isForeignTaxResidency=TRUE when main address country is not DE

  • Ensure activeNfeType is provided when fatcaClassification is ACTIVE_NFE

  • Resubmit the corrected legal entity update

2. Manual Review Required (Asynchronous Decision)

When it occurs:

  • Regular Review (reason: LEGAL_ENTITY_UPDATE): For legal entities with ACTIVE status:

    • Update of legalName - requires documents: CURRENT_REGISTRY_EXTRACT, SHAREHOLDER_LIST, TRANSPARENCY_REGISTER_EXTRACT

    • Update of legalForm - requires documents based on legal form type

    • Legal entity status changes to REVIEW and admin task is created with LEGAL_ENTITY_UPDATE reason

  • Compliance Review (reason: COMPLIANCE_REVIEW): For legal entities with ACTIVE status:

    • Address updates when country is US or prohibited (not in whitelisted residencies) - requires CURRENT_REGISTRY_EXTRACT document

    • NACE sector updates when any sector is prohibited (banned NACE codes)

    • FATCA/CRS declaration updates:

      • sanctionedCountries changed to TRUE

      • activeNfeType changed to NON_PROFIT_ORGANISATION

    • Legal entity status changes to REVIEW and admin task is created with COMPLIANCE_REVIEW reason

Business Impact:

  • Legal entity update status is set to REVIEW

  • Admin is notified for manual verification

  • Legal entity update is temporarily suspended

  • Partner receives notification about review status via webhook/notification

Review Process:

  • Admin task process is initiated for manual review

  • Admin reviews the proposed changes and their impact

  • Admin can approve, reject, or approve and suspend globally (for compliance review)

  • Decision callback returns to the legal entity update process

  • After admin approval, process continues with KYC verification (if status was ACTIVE) or direct update (if status was CREATED)

3. Automatic Approval (Direct Update)

When it occurs:

  • All validations pass (both immediate and asynchronous)

  • No review requirements detected: Changes do not involve fields requiring manual review

  • Legal entity has CREATED or ACTIVE status

  • All required documents for legal entity in status ACTIVE are provided and valid

  • Geographic and compliance requirements are met

  • No banned NACE sectors (for CREATED status) or banned sectors allowed (for ACTIVE status, no review triggered)

  • FATCA/CRS requirements are met

Business Impact:

  • Legal entity data is successfully updated in the system

  • Partner receives success notification via webhook/notification

  • Updated data is immediately available for use

4. KYC Screening Failure (Legal Entity in status ACTIVE)

When it occurs:

  • KYC screening identifies compliance issues with updated legal entity data

  • External provider flags data as suspicious or requiring additional verification

  • Updated information conflicts with regulatory databases or watchlist

  • Data authenticity cannot be verified by external screening services

Business Impact:

  • Legal entity update is rejected or routed to manual review based on severity

  • Admin task is created for compliance team verification with KYC_SUSPICIONS reason

  • Legal entity may be flagged for enhanced monitoring or rejected globally

Review Process:

  • Compliance admin reviews KYC screening results and data conflicts

  • Admin can approve with additional monitoring, request more documentation, or reject globally

  • Decision callback returns to the legal entity update process

Business Rules

Status-Based Update Rules

  • CREATED or ACTIVE status: Only legal entities with CREATED or ACTIVE status can be updated

  • All other statuses: Updates are not allowed regardless of status

  • CREATED status: No document requirements, no KYC check, no review requirements

  • ACTIVE status: Document requirements apply, KYC check is performed, review may be required

Vendor Restriction Rules

When vendor was used for the creation of the legal entity, the following vendor-provided fields cannot be updated:

  • legalName

  • legalForm

  • naceSectors

  • taxNumber

  • vatId

  • isListed

  • listedAt

  • legalEntityIdentifier (LEI)

  • purpose

  • fatcaCrsDeclaration

Fields that can be updated even when vendor was used:

  • mainAddress, correspondenceAddress, invoiceAddress

  • averageProfit, averageRevenue, liquidAssets

  • lastAnnualFinancialStatement

  • externalId

Document Requirements

  • Document IDs must be provided for legal entity in status ACTIVE and fields: legalName, legalForm, addresses

  • Document type must match field requirements (see Required Documents section)

  • Documents must exist and be associated with the legal entity

  • Multiple document types can be provided via multiple documentIds (all required types must be present)

NACE Sectors Rules

Static Validations (Synchronous):

  • NACE sector code must not be empty

  • NACE sector section format is validated (if provided)

  • Duplicate NACE sectors are not allowed

  • Note: Banned sectors validation is not performed in static validations

Business Validations (Asynchronous):

  • Only valid NACE sectors for legal entities are accepted

  • Invalid sectors return validation error

  • Sectors are automatically normalized during validation

  • For CREATED status: banned sectors are not allowed (validation error)

  • For ACTIVE status: banned sectors are allowed but trigger compliance review

Geographic Rules

Static Validations (Synchronous):

  • For CREATED status: US addresses are not allowed (validation error)

  • For ACTIVE status: US addresses are allowed but trigger compliance review

  • Main address changes to non-German countries require fatcaCrsDeclaration.isForeignTaxResidency to be set to TRUE

Business Validations (Asynchronous):

  • Address updates require CURRENT_REGISTRY_EXTRACT document (ACTIVE status)

  • Non-whitelisted residency countries trigger compliance review (ACTIVE status)

FATCA/CRS Rules

Static Validations (Synchronous):

  • When FATCA classification is ACTIVE_NFE, activeNfeType must be provided

  • When main address country is not DE, isForeignTaxResidency must be set to TRUE

  • For CREATED status: isSanctionedCountries=true is not allowed (validation error)

  • For CREATED status: activeNfeType=NON_PROFIT_ORGANISATION is not allowed (validation error)

  • For ACTIVE status: isSanctionedCountries=true and activeNfeType=NON_PROFIT_ORGANISATION are allowed but trigger compliance review

Business Validations (Asynchronous):

  • When FATCA classification is PASSIVE_NFE, all Legal Representatives and Beneficial Owners must have complete tax information (taxResidencies and taxIds)

LEI (Legal Entity Identifier) Rules

  • LEI is validated through vendor API when legalEntityIdentifier is updated

  • LEI data (status, validUntil) is retrieved from vendor API

  • LEI format and structure are validated

  • Invalid or not found LEI returns validation error

Review Requirements

Regular Review (LEGAL_ENTITY_UPDATE reason):

  • Triggered by: legalName or legalForm updates (ACTIVE status)

  • Requires documents as specified in Required Documents section

  • Legal entity status changes to REVIEW

  • Admin task created with LEGAL_ENTITY_UPDATE reason

Compliance Review (COMPLIANCE_REVIEW reason):

  • Triggered by:

    • Address updates to US or prohibited countries (ACTIVE status)

    • NACE sector updates with banned codes (ACTIVE status)

    • sanctionedCountries changed to TRUE (ACTIVE status)

    • activeNfeType changed to NON_PROFIT_ORGANISATION (ACTIVE status)

  • Legal entity status changes to REVIEW

  • Admin task created with COMPLIANCE_REVIEW reason

KYC Verification Rules (ACTIVE status only)

  • KYC re-verification is triggered before update is applied

  • KYC verification is performed after admin approval (if review was required)

  • KYC verification is performed directly after validation (if no review required)

  • For CREATED status: KYC check is skipped

  • KYC outcomes:

    • Valid → proceed to update

    • Manual Review Required → create admin task with KYC_SUSPICIONS reason

    • Repeat KYC → trigger repeat verification

    • Rejected → stop update process

Last updated