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