Legal Entity Create Process

This document describes the overall process for creating new legal entities on the platform, from initial data submission, through validation and review stages, to the final creation of the legal entity record or handling of exceptions.

Overview

The Legal Entity Creation Process ensures the integrity and compliance of legal entity data by performing comprehensive validation and review procedures. This process protects against incorrect data, maintains data quality standards, and ensures regulatory compliance across all platform operations. Legal entities are organizations representing legal persons such as companies, foundations, associations, etc.

Prerequisites

Partners need to:

  • Gather all required legal entity information

  • Ensure proper authorization to create legal entities

  • Provide necessary identification data for the legal entity

Validation Types

The legal entity 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

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

  • Format validation - Validates field formats using regex patterns where applicable

  • Data type validation - Ensures correct data types for all 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 Validations:

  • FATCA CRS Declaration - Validates that the FATCA CRS declaration is provided and correct

    • Ensure the isSanctionedCountries field is set to false, indicating the legal entity doesn't conduct business activities with parties from a country that is on a sanctions list or has been categorized as a high-risk country.

    • Ensure the activeNfeType fields is not empty, if filed fatcaClassification equals ACTIVE_NFE

  • NACE sectors validation - Checks if NACE sector list is not empty and does not contain duplicates

  • External ID validation - Ensures the externalId field is unique across the partner

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, status checks, and relationship validations specific to legal entity creation.

Asynchronous validations include:

  • Checking if the externalId field is unique across partner

  • Global existence validation - Verifies if the legal entity with the same basic data already exists globally

    • If it exists, uses the existing globalId

    • If it doesn't exist, creates a new globally unique record

  • NACE sectors validation if they are valid and not banned

  • Local existence validation - Checks if the legal entity already exists locally for the partner

    • If it exists, returns an error indicating the existing legal entity

Business Process Flow

The creation process follows a structured workflow:

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

  2. Command Event Publishing - Legal entity create command event is published

  3. Data Storage - Legal entity data is stored with RECEIVED status

  4. Asynchronous Business Validation - Comprehensive verification and routing decisions

  5. Legal Entity Creation - Official creation in the system

  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/legal-entities

Validation Framework

Data Quality Assurance

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

Initial Data Verification

  • Ensures all required legal entity information is provided

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

  • Confirms proper partner authorization

Business Validation Steps (Asynchronous)

  1. Global Existence Validation

    • Checks if the legal entity with the same basic data already exists globally

    • If exists, uses the existing globalId and updates global data

    • If doesn't exist, creates a new globally unique record

  2. NACE Sectors Validation and Normalization

    • Retrieves valid NACE sectors for legal entities

    • Retrieves banned NACE sectors

    • Validates and normalizes the provided NACE sectors

    • Returns validation error if NACE sectors are invalid or banned

  3. Schema Validation

    • Performs comprehensive legal entity schema validation

    • Verifies all fields comply with schema definitions

    • Returns validation error if schema is invalid

  4. Data Creation or Update

    • For new legal entity: creates new record with CREATED status

    • For globally existing legal entity: updates global data and creates partner-specific data

    • Returns error if record already exists locally for the partner

Business Outcomes

1. Data Validation Failure (Immediate Rejection)

When it occurs:

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

    • Missing required fields (e.g., legalName, legalForm, registerCountry)

    • Missing activeNfeType field when fatcaClassification = ACTIVE_NFE

    • Invalid data formats

  • External ID already exists for the partner

Business Impact:

  • Legal entity 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 and correctly formatted

  • Resubmit the corrected legal entity data

2. Asynchronous Validation Failure

When it occurs:

  • Banned NACE sectors

  • Invalid NACE sectors

  • Legal entity already exists locally for the partner

  • At least one of the field is invalid or does not comply with schema definition

Business Impact:

  • Legal entity creation is rejected

  • Partner receives detailed validation error notification via webhook/notification

  • No legal entity record is created in the system

Next Steps:

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

  • Check that NACE sectors are allowed and valid

  • Verify legal entity doesn't already exist for the partner in the system

  • Resubmit legal entity creation request after resolving validation issues

3. Successful Creation

When it occurs:

  • All validations pass (both immediate and asynchronous)

  • NACE sectors are valid and allowed

  • Legal entity doesn't exist locally for the partner or can be linked to existing global record

Business Impact:

  • Legal entity is successfully created in system

  • Legal entity status is set to CREATED

  • Partner receives success notification via webhook/notification

Business Rules

Data Requirements

  • Legal entities must have all required fields according to schema

  • NACE sectors must be valid and allowed

Global Existence Rules

  • If legal entity with same basic data already exists globally, the existing globalId will be used

  • Global data will be updated with new information

  • Partner-specific data will be created for the partner

Local Existence Rules

  • If legal entity already exists locally for the partner, creation will be rejected

  • Partner will receive an error indicating the existing legal entity

NACE Sectors Rules

  • NACE sectors must be valid according to allowed sectors list

  • Banned NACE sectors are not allowed

  • NACE sectors will be normalized before saving

Status Rules

  • New proxies are created with RECEIVED status initially

  • New legal entities are created with initial status CREATED

Last updated