Cash accounts

Cash accounts are the single-currency accounts where transactions are booked. Every cash account belongs to an entity and carries a single currency, fixed at creation. Custodian feeds and manual transactions both land on cash accounts.

Reads need structure:read, writes structure:write. Every write takes ?dry_run=true and an Idempotency-Key header (see Writes), and is logged in the change list. A body field a write does not know answers 400, and so does a query parameter the list does not know.

Data model

idstring: Stable identifier for the cash account. A UUID — treat it as opaque.
entity_idstring: The entity that owns the cash account. Set at creation, immutable afterwards.
namestring or null: Display name shown in the product. null when the cash account has no name.
currency_codestring: ISO 4217 code of the cash account's currency. Fixed at creation — a cash account holds exactly one currency.
external_identifierstring or null: The cash account's id at its bank — an IBAN or an account number. null when not known.
custodian_idstring or null: The bank, from custodians. null when not known.
connection_typestring or null: How the cash account is fed: aggregator, custodian_feed or manual. null when not known.
managedboolean: true when Aleta runs the cash account. Set it when you create the cash account; afterwards you can hand a cash account to Aleta, but only Aleta sets it back to false.
release_modestring or null: How the cash account's data is released: manual, auto or planned. null when its release group decides. Linked cash and custody accounts are released together, so they share one release mode.
valid_fromdate or null: The first day the cash account holds, inclusive. null when it holds from the beginning.
valid_todate or null: The last day the cash account holds, inclusive. null while it is open.
custody_account_idsarray of strings: The custody accounts the cash account is linked to on the day read.
investment_manager_idstring or null: The investment manager the cash account is run by. null when none is set.
period_lock_appliesboolean: true when the cash account follows its entity's period lock: a write dated on or before the entity's closing date is refused. Only Aleta sets it.
originstring: v1 when the cash account was made in v1, legacy when it comes from the legacy platform. A legacy cash account is read-only until your move to v1 is done.

GET/v1/cash-accounts

List cash accounts

Returns the cash accounts visible to the authenticated credential that hold on as_of, oldest first, in the standard v1 list envelope. Deleted cash accounts are not listed. A malformed entity_id, as_of or cursor is a 400.

Query parameters

entity_idstring: Only the cash accounts of this entity.
as_ofdate: Only the cash accounts that hold on this day, with their links as they stood then. Defaults to today (UTC); the answer's as_of shows the day read.
limitinteger: Page size. Defaults to 100, capped at 1 000.
cursorstring: Opaque cursor from the previous page's next_cursor. Omit for the first page.

Request

GET/v1/cash-accounts

curl -G https://api.aleta.ai/v1/cash-accounts \
  -H "Authorization: Bearer {access_token}" \
  -d entity_id=019eb3d2-fc2e-7782-973e-af78d0c10fa6 \
  -d limit=1

Response

{
  "data": [
    {
      "id": "019dff7d-5ab5-7ed4-a78d-93f03070e34b",
      "entity_id": "019eb3d2-fc2e-7782-973e-af78d0c10fa6",
      "name": "Cash DKK",
      "currency_code": "DKK",
      "external_identifier": "DK5000400440116243",
      "custodian_id": "019c0a52-1f0e-7a31-9a5b-3f1d2c7e8a10",
      "connection_type": "custodian_feed",
      "managed": false,
      "release_mode": null,
      "valid_from": "2026-01-01",
      "valid_to": null,
      "custody_account_ids": ["019f8d70-9b1a-7c44-8e2f-0a6b5c4d3e21"],
      "investment_manager_id": null,
      "period_lock_applies": true,
      "origin": "v1"
    }
  ],
  "next_cursor": null,
  "limit": 1,
  "as_of": "2026-10-18"
}

POST/v1/cash-accounts

Create a cash account

Creates a cash account under an existing entity, in your v1 release group, so it is released apart from the cash and custody accounts that come from the legacy platform. Choose the currency carefully — it cannot be changed afterwards. Returns 201 with the created cash account.

Refusals, in this order: 400 for the body (an unknown field, a missing required field, a blank name, an unknown currency, a feed without custodian_id), 404 for an entity_id that is malformed or that you cannot see, 403 when your grants do not cover the entity whole with a grant that writes (an auditor or lens viewer grant does not), 400 for a custodian_id that is no custodian, and 409 duplicate_account when an open cash account has the same external_identifier at the same bank, with next_action pointing to PATCH /v1/cash-accounts/{id} of the cash account already there.

Body parameters

entity_idstring: The entity to create the cash account under. Required.
currency_codestring: ISO 4217 currency for the cash account. Required, immutable after creation; an unknown code is a 400.
connection_typestring: aggregator, custodian_feed or manual. Required.
custodian_idstring: The bank, from custodians. Required unless connection_type is manual.
valid_fromdate: The first day the cash account holds. Required.
namestring: Display name, not blank. Optional.
external_identifierstring: The cash account's id at its bank. Optional.
release_modestring: manual, auto or planned. Optional.
investment_manager_idstring: The investment manager. Optional.
managedboolean: true when Aleta is to run the cash account. Defaults to false.

Request

POST/v1/cash-accounts

curl -X POST https://api.aleta.ai/v1/cash-accounts \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{
    "entity_id": "019eb3d2-fc2e-7782-973e-af78d0c10fa6",
    "currency_code": "DKK",
    "connection_type": "custodian_feed",
    "custodian_id": "019c0a52-1f0e-7a31-9a5b-3f1d2c7e8a10",
    "valid_from": "2026-01-01",
    "name": "Cash DKK",
    "external_identifier": "DK5000400440116243"
  }'

GET/v1/cash-accounts/{id}

Retrieve a cash account

Fetch a single cash account by id, also one that has been closed, with its links as of today. Returns the bare object, or a 404 problem when the id is malformed, doesn't exist for this tenant, or the cash account is deleted.

Request

GET/v1/cash-accounts/{id}

curl https://api.aleta.ai/v1/cash-accounts/019dff7d-5ab5-7ed4-a78d-93f03070e34b \
  -H "Authorization: Bearer {access_token}"

PATCH/v1/cash-accounts/{id}

Update a cash account

Partially updates a cash account and returns 200 with it. entity_id and currency_code are immutable — to change either, create a new cash account. Close a cash account by setting valid_to.

Writing to a cash account takes a grant that covers it whole: the tenant, its client, its entity or the cash account itself. A grant on a party or a lens does not, nor does an auditor or lens viewer grant. Refusals, in this order: 400 for the body (an unknown field, a blank name), 403 for period_lock_applies from anyone but Aleta, 404 when the id is malformed or you cannot see the cash account, 403 when your grants do not cover it, 409 legacy_managed for a legacy cash account before your move to v1, then the write's own refusals: 403 for managed set from true to false by anyone but Aleta, 400 for a custodian_id that is no custodian, a feed without a bank or a valid_to before valid_from, 409 period_locked for a period change that touches a closed day, 403 when your grants do not cover every cash and custody account a new release_mode moves, and 409 duplicate_account when another open cash account has the new bank and id (next_action points to it).

Body parameters

namestring or null: New display name, not blank, or null to clear it.
external_identifierstring or null: New id at the bank (it replaces the old one), or null to clear it.
custodian_idstring or null: The bank, or null to clear it. A cash account fed by aggregator or custodian_feed keeps a bank: clearing it is a 400.
connection_typestring: aggregator, custodian_feed or manual. A feed needs a bank: without one it is a 400.
investment_manager_idstring or null: The investment manager, or null to clear it.
release_modestring or null: manual, auto or planned, or null to let the release group decide. Linked accounts are released together: the new mode moves every custody and cash account linked to this one today, each logged as its own change. Your grants must cover them all (403 otherwise).
valid_fromdate or null: A new first day, or null for "from the beginning".
valid_todate or null: The last day the cash account holds, or null to reopen it. Its links to custody accounts end on that day too.
managedboolean: true hands the cash account to Aleta. Only Aleta sets it back to false; anyone else gets 403.
period_lock_appliesboolean: Aleta only; anyone else gets 403.

A change to valid_from or valid_to on a cash account with period_lock_applies is refused with 409 period_locked when the first day it changes is on or before the entity's closing date; moving an open start always reaches a closed day. next_action points to PUT /v1/entities/{id}/period-lock.

Request

PATCH/v1/cash-accounts/{id}

curl -X PATCH https://api.aleta.ai/v1/cash-accounts/019dff7d-5ab5-7ed4-a78d-93f03070e34b \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{ "valid_to": "2026-12-31" }'

DELETE/v1/cash-accounts/{id}

Delete a cash account

Removes a cash account that nothing uses and returns 204. Refusals, in this order: 404 when the id is malformed or you cannot see the cash account, 403 when your grants do not cover it, 409 legacy_managed for a cash account from the legacy platform until your move to v1 is done, and 409 in_use for a cash account in use.

A cash account with transactions, holdings, lots, invalid transactions, reconciliation breaks, a custody account linked to it today or later, or other data is not deleted: the answer is 409 in_use, its detail names what uses it, and next_action points to PATCH /v1/cash-accounts/{id} with valid_to, which closes it instead.

Request

DELETE/v1/cash-accounts/{id}

curl -X DELETE https://api.aleta.ai/v1/cash-accounts/019f8d70-989c-79c6-a6e5-b78b2b8f7413 \
  -H "Authorization: Bearer {access_token}" \
  -H "Idempotency-Key: {uuid}"

POST/v1/cash-accounts/{id}/release

Release a cash account

Releases a cash account in release mode manual by hand, together with the custody and cash accounts linked to it. Needs platform:write, not structure:write. The body, the refusals and the answer are those of releasing a custody account. A release that passes every check answers 409 release_unavailable; no release is queued.

Request

POST/v1/cash-accounts/{id}/release

curl -X POST https://api.aleta.ai/v1/cash-accounts/019dff7d-5ab5-7ed4-a78d-93f03070e34b/release \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{}'

Custody accounts — the securities accounts a cash account is linked to.
Transactions — the ledger rows booked against a cash account.
Entities — the owner a cash account belongs to.