Legal Entity Management

A legal entity represents a distinct legal business unit within your organization. Each entity maintains its own chart of accounts, tax registrations, fiscal periods, and transactions -- while sharing master data across the organization for efficiency.

---

What is a Legal Entity?

Legal entities are the foundational building blocks of your organizational structure. Each entity operates with its own:

• Chart of accounts -- entity-specific account structures
• Tax registrations -- VAT, sales tax, and other registrations
• Fiscal periods -- independent period management
• Transactions -- all financial data filtered by entity
• Agent email addresses -- dedicated inboxes for bills, invoices, payments, and receipts

Key Properties

Fields marked "No" are structural -- changing them would invalidate existing transaction data, account structures, or reporting hierarchies.

---

Creating Entities

Via Admin Dashboard

1. Navigate to the Entities page and click Create entity
2. Fill in entity details: name, code, currency, country, type, accounting standard
3. Toggle VAT Registered if applicable
4. Click Create entity

The entity code auto-generates from the name (uppercase, dashes) but can be manually edited before creation.

During Organization Setup

When creating a new client organization, the primary legal entity is created atomically with full infrastructure:

• Chart of accounts
• Fiscal periods
• Tax codes
• Payment terms
• GL posting profiles
• Number series
• Agent email addresses
• Agent definitions
• VAT registration record (if enabled)

Adding Entities to Existing Organizations

Additional entities can be added to existing organizations through the admin dashboard or programmatically. Each new entity receives the same infrastructure setup as the primary entity.

---

Entity Types

---

Viewing Entities

Entity List

The entity list displays all entities with key information:

• Name, code, currency, country, type
• VAT status -- green badge for VAT-registered entities
• Active status -- active/inactive indicator

Entity Detail

The detail view shows comprehensive entity information:

• Statistics: account count, transaction count, fiscal period count, status
• Profile: currency, reporting currency, country, entity type, tax ID, VAT registration, creation date
• Agent email addresses: entity-specific emails for automated document processing (bills@, invoices@, payments@, receipts@)
• Address: registered business address

---

Updating Entities

Updatable Fields

Non-Updatable Fields

Confirmation Flow

Entity updates use a two-step confirmation pattern to prevent accidental changes:

1. Preview -- the system shows proposed changes with before/after values
2. Confirm -- explicitly confirm to apply the changes

This ensures you see exactly what will change before committing, preventing accidental overwrites of critical properties.

---

VAT Registration Management

VAT registration status controls how the system handles tax posting on transactions.

Where VAT Status is Managed

How It Works

Enabling VAT registration:

1. Checks for existing active registration (skips if already registered)
2. Attempts to reactivate a previously deactivated registration
3. Creates a new registration record if none exists

Disabling VAT registration:

• Soft-deactivates the registration with an effective end date
• Historical transactions retain their VAT treatment

Important Restrictions

• Reverse charge tax codes are blocked for non-VAT entities
• VAT status checks use the transaction date (not today's date) -- backdated entries respect historical registration status
• The registration number uses the entity's tax ID, falling back to "PENDING" if no tax ID is set

---

Entity Lifecycle

Created (via dashboard, organization setup, or API)
    |
    v
Active (operational, accepting transactions)
    |  Toggle VAT registration as needed
    |  Update name, address, tax ID
    v
Inactive (deactivated)
    |  Can be reactivated
    v
Active (reactivated)

Deactivation

Entities are never hard-deleted -- they are deactivated. Inactive entities:

• Are hidden from the entity list by default (unless "Show inactive" is toggled)
• Cannot have new transactions posted
• Remain visible in all historical reports
• Can be reactivated at any time

---

Agent Email Addresses

Each legal entity receives dedicated email addresses for automated document processing:

These addresses are automatically configured during entity creation and integrate with the AI agent system for automated document processing.

---

Audit Trail

All entity updates are logged through the workflow system with full before/after state tracking. This provides:

• Complete history of who changed what and when
• Before and after values for every field modification
• Approval chain documentation
• Compliance-ready audit records

---

Multi-Currency Support

Each entity operates with two currency settings:

• Functional currency -- the primary currency for day-to-day transactions (e.g., USD, EUR, GBP)
• Reporting currency -- the currency used for consolidated group reports

These are set during entity creation and cannot be changed afterward, as all transaction amounts are stored in the functional currency.

---

Related Documentation

• Tax Management -- how VAT registration affects transaction posting
• Accounts Management -- entity-specific chart of accounts
• Workflow Management -- approval workflows for entity changes