Skip to main content
Use Midaz Module to manage Accounts associated with your Ledger. Accounts are the fundamental units that hold balances and participate in transactions within your financial system.

​
What are Accounts?

Accounts represent individual balance holders within your ledger structure. Each account:
  • Holds balances in a specific asset (currency or commodity)
  • Participates in transactions as sources or destinations of funds
  • Belongs to an entity such as a customer, business unit, or external party
  • Supports portfolios, segments, and account types for organization and reporting
  • Tracks history with complete audit trails of all movements
Accounts can be classified as:
  • Internal Accounts - Accounts you create and manage for your organization’s operations
  • External Accounts - Midaz creates these automatically for external assets or liabilities
For technical details, refer to the Accounts page.

​
Key concepts

  • Account Types - Classify accounts according to your organization’s financial structure (e.g., checking, savings, revenue). Enable validation to enforce account type rules.
  • Account Alias - A unique, human-readable identifier (e.g., @customer_john_doe) that makes it easier to reference accounts in transactions and queries.
  • Portfolios - Group related accounts together for reporting and management purposes. Useful for tracking customer portfolios or business divisions.
  • Segments - Organize accounts into hierarchical structures for complex organizational needs like cost centers or departments.

​
Accessing the Accounts page

To open the Accounts page, select the Accounts option in the Accounts section of the left sidebar menu. The Accounts page displays a table with all Accounts in the current Ledger, including:
  • Account Name - The account’s display name
  • ID - The account’s unique identifier
  • Account Alias - The unique, human-readable alias (if set)
  • Assets - The asset (currency or commodity) the account holds
  • Metadata - The number of custom key-value pairs on the account
  • Portfolio - The portfolio the account belongs to (if any)
  • Actions - The three-dots menu with the available actions — external accounts show a padlock icon instead
The padlock icon marks an account you cannot edit or delete. Midaz creates these external accounts automatically when you create an Asset.

​
Available actions

From the Accounts page, you can:

Create an Account

Add internal accounts for customers, departments, or business operations

Edit Account information

Modify account details, metadata, and organizational settings

Delete an Account

Delete accounts you no longer need (internal accounts only)

​
Account organization strategies

Create separate accounts for each customer, organized by account type and asset code.Example:
  • Customer checking account: @customer_123_checking (Type: checking, Asset: USD)
  • Customer savings account: @customer_123_savings (Type: savings, Asset: USD)
  • Group both under a Portfolio: Customer 123 Portfolio
Create dedicated treasury accounts to manage liquidity and operational funds.Example:
  • Main treasury: @treasury_main (Type: treasury, Asset: USD)
  • Reserve fund: @treasury_reserve (Type: reserve, Asset: USD)
  • Float account: @float_operations (Type: float, Asset: USD)
Create separate accounts for each currency your organization handles.Example:
  • USD operations: @ops_usd (Type: operations, Asset: USD)
  • EUR operations: @ops_eur (Type: operations, Asset: EUR)
  • BRL operations: @ops_brl (Type: operations, Asset: BRL)
Use segments and account types to track departmental expenses.Example:
  • Engineering expenses: @eng_expenses (Type: expense, Segment: Engineering)
  • Marketing expenses: @mkt_expenses (Type: expense, Segment: Marketing)
  • Consolidate with parent segment for organization-wide reporting

​
Account type validation

Account type validation makes each account follow your organization’s financial structure.

​
Enabling Account type validation

Account type validation is a per-ledger setting. To turn it on in the Console: on the Ledgers page, open the Ledger’s Details, click the Settings tab, and toggle on Validate Account Type. As a programmatic alternative, send a PATCH request to /v1/organizations/{organization_id}/ledgers/{ledger_id}/settings with this body:
When you enable account type validation, each new account must have a registered account type. Update existing accounts that have no type.
For more information about managing account types, see Managing Account Types.

​
Best practices

1

Use descriptive names and aliases

Name accounts clearly and use aliases for easy reference (e.g., @customer_john_checking instead of UUID references).
2

Use account types

Enable account type validation to enforce your chart-of-accounts structure and prevent misclassification.
3

Organize with portfolios

Group related accounts into portfolios for better reporting and management, especially for customer relationships.
4

Plan your asset codes

Use consistent asset code conventions (ISO 4217 for currencies) to simplify multi-currency operations.
5

Document with metadata

Use metadata fields to store additional context like customer IDs, department codes, or integration references.
Accounts are the foundation of your ledger. A clear account structure improves your financial operations and reporting.