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. Inside a client, legal entities form an ownership tree; underneath each legal entity sit accounts (the cash containers) and depositories (the custody relationships that hold assets). Every position the platform tracks lives inside one of these.

Data model

Legal entity

JSON:API resource type: legal-entity.

Name
id
Type
string
Description
Stable identifier, scoped to the parent client.
Name
name
Type
string
Description
Display name. Defaults to the registered legal name but can be overridden for readability inside the product.

Account

JSON:API resource type: account. An account is a cash container at a custodian — typically a current account in a single currency.

Name
id
Type
string
Description
Stable identifier.
Name
name
Type
string
Description
Display name shown in the product.
Name
externalIdentifier
Type
string
Description
The account number as the custodian knows it. Not unique across custodians — pair with the depository the account hangs off for a globally unique key.
Name
ccyCode
Type
ISO-4217 code
Description
Operating currency of the account. Cash positions are denominated here; consolidated reports convert at the day's FX rate.
Name
excludeFromReporting
Type
boolean
Description
When true the account is hidden from consolidated reports — useful for legacy accounts kept on the books for completeness without polluting performance.

Relationships

Name
legalEntity
Type
legal-entity
Description
The legal entity that owns the account.
Name
depositories
Type
array of depository
Description
The depositories that back this account. An account can be split across more than one depository for cash-and-securities accounts.

Depository

JSON:API resource type: depository. A depository is a specific custody relationship — "Our Nordea private-banking relationship," "Our Saxo brokerage." It's the bridge between the legal entity and the live custodian feed.

Name
id
Type
string
Description
Stable identifier.
Name
name
Type
string
Description
Display name.
Name
externalIdentifier
Type
string
Description
The depository identifier as the custodian assigns it.

Relationships

Name
accounts
Type
array of account
Description
Accounts that settle through this depository.

Relationships

Ownership edges

Client
└── Legal entity
    ├── Account (cash, by ccyCode)
    └── Depository (custody relationship)
        └── 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. See Reporting entities.

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

List legal entities

Returns the full ownership set for one client. The response is flat — there is no parent/child hierarchy on a v2 legal entity, so reconstruct any grouping you need client-side.

Request

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

curl https://platform.aleta.io/api/v2/clients/{client_id}/legal-entities \
  -H "Authorization: Bearer {access_token}"

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

Retrieve a legal entity

Single-record lookup. Useful for refreshing a held reference or following a relationship pointer in another payload.

Request

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

curl https://platform.aleta.io/api/v2/legal-entities/{id} \
  -H "Authorization: Bearer {access_token}"

POST/api/v2/clients/{id}/legal-entities

Create a legal entity

Adds a legal entity under the client. The only required attribute is name.

Request

POST/api/v2/clients/{id}/legal-entities

curl -X POST https://platform.aleta.io/api/v2/clients/{client_id}/legal-entities \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "legal-entity",
      "attributes": { "name": "Andersen Family Trust" }
    }
  }'

PATCH/api/v2/legal-entities/{id}

Update a legal entity

Patches the display name. The legal entity's owning client cannot be changed — create a new entity under the new client and migrate accounts if you need to re-parent.

Request

PATCH/api/v2/legal-entities/{id}

curl -X PATCH https://platform.aleta.io/api/v2/legal-entities/{id} \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "legal-entity",
      "id": "{id}",
      "attributes": { "name": "Andersen Family Trust (renamed)" }
    }
  }'

DELETE/api/v2/legal-entities/{id}

Delete a legal entity

Removes the legal entity. Only allowed when no accounts, depositories, or active custodian authorities still reference it.

Request

DELETE/api/v2/legal-entities/{id}

curl -X DELETE https://platform.aleta.io/api/v2/legal-entities/{id} \
  -H "Authorization: Bearer {access_token}"

GET/api/v2/legal-entities/{id}/accounts

List accounts

Returns every account hanging off the legal entity. Accounts are cash containers — for invested positions, follow the depository relationship.

Request

GET/api/v2/legal-entities/{id}/accounts

curl https://platform.aleta.io/api/v2/legal-entities/{id}/accounts \
  -H "Authorization: Bearer {access_token}"

GET/api/v2/accounts/{id}

Retrieve an account

Single-account lookup.

Request

GET/api/v2/accounts/{id}

curl https://platform.aleta.io/api/v2/accounts/{id} \
  -H "Authorization: Bearer {access_token}"

POST/api/v2/legal-entities/{id}/accounts

Create an account

Adds a cash account under the legal entity. ccyCode is required and immutable — opening an account in a new currency means creating a new account.

Request

POST/api/v2/legal-entities/{id}/accounts

curl -X POST https://platform.aleta.io/api/v2/legal-entities/{id}/accounts \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "account",
      "attributes": {
        "name": "Nordea operating cash",
        "externalIdentifier": "DK12-0001-2345-6789",
        "ccyCode": "DKK",
        "excludeFromReporting": false
      }
    }
  }'

PATCH/api/v2/accounts/{id}

Update an account

Patches name, externalIdentifier, or excludeFromReporting. ccyCode and the owning legal entity are immutable.

Request

PATCH/api/v2/accounts/{id}

curl -X PATCH https://platform.aleta.io/api/v2/accounts/{id} \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "account",
      "id": "{id}",
      "attributes": { "excludeFromReporting": true }
    }
  }'

DELETE/api/v2/accounts/{id}

Delete an account

Removes an account. Allowed only when there are no holdings or transactions still booked against it.

Request

DELETE/api/v2/accounts/{id}

curl -X DELETE https://platform.aleta.io/api/v2/accounts/{id} \
  -H "Authorization: Bearer {access_token}"

GET/api/v2/legal-entities/{id}/depositories

List depositories

Returns every depository belonging to the legal entity. Depositories are the integration handle on a custodian — the link target for ingesting holdings and transactions.

Request

GET/api/v2/legal-entities/{id}/depositories

curl https://platform.aleta.io/api/v2/legal-entities/{id}/depositories \
  -H "Authorization: Bearer {access_token}"

GET/api/v2/depositories/{id}

Retrieve a depository

Single-depository lookup.

Request

GET/api/v2/depositories/{id}

curl https://platform.aleta.io/api/v2/depositories/{id} \
  -H "Authorization: Bearer {access_token}"

POST/api/v2/legal-entities/{id}/depositories

Create a depository

Adds a depository under the legal entity. Once created, the depository is wired to a live data feed by granting a custodian authority.

Request

POST/api/v2/legal-entities/{id}/depositories

curl -X POST https://platform.aleta.io/api/v2/legal-entities/{id}/depositories \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "depository",
      "attributes": {
        "name": "Nordea Private Banking",
        "externalIdentifier": "NDA-PB-12345"
      }
    }
  }'

PATCH/api/v2/depositories/{id}

Update a depository

Patches name or externalIdentifier. The owning legal entity cannot be changed.

Request

PATCH/api/v2/depositories/{id}

curl -X PATCH https://platform.aleta.io/api/v2/depositories/{id} \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "depository",
      "id": "{id}",
      "attributes": { "name": "Nordea PB (renamed)" }
    }
  }'

DELETE/api/v2/depositories/{id}

Delete a depository

Removes the depository. Allowed only when no accounts are linked and no active custodian authority is attached.

Request

DELETE/api/v2/depositories/{id}

curl -X DELETE https://platform.aleta.io/api/v2/depositories/{id} \
  -H "Authorization: Bearer {access_token}"

Reporting entities — the projection that consolidates legal-entity holdings into reporting buckets.
Auth flows (v3) — the onboarding procedures available per custodian.
Authorities (v3) — the consent records that connect a depository to a live feed.