Entities

Aleta has two kinds of "entity" and the distinction matters. Legal entities describe who owns what in a regulatory sense; reporting entities describe how the client wants to analyse the portfolio. Most integrations need to touch both, and picking the right one is the difference between an intuitive UI and a confusing one.

The legal entity tree mirrors the real-world ownership structure. It's what shows up on paper — the trust deed, the shareholder register, the certificate of incorporation. Aleta supports four types:

  • Name
    individual
    Type
    natural person
    Description

    A human being acting in their own name — a principal, a spouse, an adult child.

  • Name
    trust
    Type
    legal vehicle
    Description

    Any trust arrangement: family trust, discretionary trust, purpose trust. Holds wealth for its beneficiaries.

  • Name
    company
    Type
    legal vehicle
    Description

    Limited companies — holding companies, investment vehicles, operating businesses that sit in the wealth structure.

  • Name
    foundation
    Type
    legal vehicle
    Description

    Foundations, charitable or private-interest. Common in succession-planning structures.

Legal entities form a tree via parent_legal_entity_id. A typical family-office shape:

Smith Family Office                  (root)
├── Smith Family Trust               (holding vehicle)
│   ├── Smith Investment Co.         (operating investment)
│   │   └── Depository @ Saxo ─ Account
│   └── Depository @ Nordea ─ Account
├── Anna Smith                       (individual, beneficiary)
└── Smith Foundation                 (philanthropic arm)

Each legal entity holds depositories — Aleta's name for a specific custody relationship. A legal entity with wealth at three custodians has three depositories; each depository can back one or more accounts depending on how the custodian structures their numbering.

Reporting entities

Reporting entities are the analytical view. They also form a tree — but it's a separate tree, tailored to how the client wants to see their data. "Family wealth total" might be the root; underneath it, "Generation 1 — liquid," "Generation 1 — illiquid," "Generation 2," "Foundation." Each reporting entity has one or more portfolios (named buckets), and each portfolio lists the accounts that belong to it.

Reporting entities solve three problems that legal entities can't:

  1. Cross-legal-entity aggregation. A reporting entity's portfolio can list accounts from multiple legal entities — useful when the family thinks of "our equity exposure" as one view regardless of which trust holds which slice.
  2. Sub-legal-entity splits. One account held in a trust might split across "Liquid" and "Strategic" portfolios — a distinction the legal structure can't express.
  3. Analytical stability. The reporting view doesn't have to change when the legal structure does. A new holding company incorporated for tax reasons slots into the legal tree without touching the reporting tree.

Why authentication cares

Access tokens are scoped per legal entity. A token minted for the Smith Investment Co. legal entity can read that entity and any child entities, but can't read the trust above it or its sibling reporting entities. This is convenient for delegated access — an external accountant who only needs the operating company gets exactly that scope, no more.

Reporting-scoped tokens exist too (for consumer dashboards), and they grant read access against a reporting entity tree without exposing the underlying legal structure.

Metadata

Every entity (legal or reporting) carries a free-form metadata object — a JSON bag for anything Aleta doesn't model first-class. Common uses: jurisdiction codes, internal CRM IDs, ultimate beneficial owner references, tax-residency flags. Metadata is indexed for equality queries and included in the entity.updated webhook so downstream systems can react.

What's next