Legal entities

Legal entities model the real-world ownership of wealth: the trusts, holding companies, foundations, and individuals that sit above the accounts at each custodian. Every legal entity belongs to a client, and every account at a custodian is held by exactly one legal entity.

Data model

Legal Entity

  • Name
    id
    Type
    string
    Description

    Stable identifier, scoped to the parent client.

  • Name
    client_id
    Type
    string
    Description

    The client this legal entity belongs to. Immutable.

  • Name
    name
    Type
    string
    Description

    Display name. Defaults to the registered legal name but can be overridden for readability inside the product.

  • Name
    type
    Type
    enum
    Description

    One of individual, trust, company, foundation. Drives the default icon + consolidation rules in reporting.

  • Name
    parent_legal_entity_id
    Type
    string | null
    Description

    Optional — forms the ownership edge that aggregates up the tree. The root legal entity of the client has no parent.

  • Name
    jurisdiction
    Type
    ISO 3166-1 alpha-2
    Description

    Country of incorporation or residence. Used for tax-reporting rollups and to apply jurisdiction-specific accounting defaults.

Account

Accounts sit underneath a legal entity and pair it with a depository (the custodian that holds the assets). The account record is the platform's handle for a real-world account number at a real bank or broker.

  • Name
    id
    Type
    string
    Description

    Stable identifier.

  • Name
    legal_entity_id
    Type
    string
    Description

    The owning legal entity.

  • Name
    depository_id
    Type
    string
    Description

    The depository (custodian relationship) that holds the positions.

  • Name
    external_reference
    Type
    string
    Description

    The account number as the custodian knows it. Not unique across custodians — pair with depository_id for a globally unique key.

  • Name
    currency
    Type
    ISO-4217 code
    Description

    The account's operating currency. Positions report in this currency before consolidation.

Depository

A depository represents a specific custody relationship — "Our Nordea private-banking relationship," "Our Saxo brokerage." One legal entity can have multiple depositories; each depository can back multiple accounts.

  • Name
    id
    Type
    string
    Description

    Stable identifier.

  • Name
    legal_entity_id
    Type
    string
    Description

    The legal entity holding this depository.

  • Name
    custodian_id
    Type
    string
    Description

    The custodian provider this depository is an instance of.

  • Name
    status
    Type
    enum
    Description

    connected, disconnected, pending. Reflects the health of the underlying data feed.

Relationships

Ownership edges

Client
  └── Legal Entity (root)
        ├── Legal Entity (child)
        │    ├── Depository ── Account ── Holdings ── Transactions
        │    └── Depository ── Account ── Holdings ── Transactions
        └── Legal Entity (child individual)
             └── Depository ── Account ── Holdings ── Transactions

Consolidated reporting against a reporting entity (not a legal entity) rolls these up — the reporting structure is a separate projection optimised for the client's internal views.

GET/v2/clients/{id}/legal-entities

Fetches the full ownership tree for one client. The response is a flat list — reconstruct the tree client-side from parent_legal_entity_id edges, or pass tree=true to receive a pre-assembled nested response.

Optional query parameters

  • Name
    tree
    Type
    boolean
    Description

    When true, the API returns the entities already assembled into a nested tree. Default false — most integrators prefer the flat shape for indexing.

  • Name
    type
    Type
    enum
    Description

    Filter by entity type — individual, trust, company, foundation.

Request

GET
/v2/clients/{id}/legal-entities
curl https://api.aleta.io/v2/clients/{client_id}/legal-entities \
  -H "Authorization: Bearer {token}"
  • Reporting entities — the layer that projects legal ownership into reporting views.
  • Custodians — the providers behind depositories.
  • Holdings — the positions inside accounts.