# 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:

```
PATCH /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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tradevest.ai/documentation/entity_role_management_after_refactor/legal_entity_update_process.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.