Creating an Account

Create a new Account in the Console, tie it to an Asset, set its alias and type, and optionally link it to a Portfolio or add metadata during setup.

You must link an Account to an existing Asset. Create the Asset before you create the Account.

Before you start

---

You need an existing Organization, Ledger, and Asset. If the Ledger uses Validate Account Type, create the required Account Types before you open this form.

Decide what the account represents before you choose its type and alias. Common examples include customer, merchant, treasury, fee revenue, settlement, suspense, and expense accounts.

Create the Account

---

To create an Account, follow these steps:

1. From the Accounts page, click the New Account button.

2. The New Account form will open on the right side of the screen with three tabs: Account Details, Portfolio, and Metadata.

3. Fill in the required information in the Account Details tab.

   For more information about the fields in the form, refer to the Field guide section.

4. (Optional) Switch to the Portfolio tab to link this account to a portfolio for reports and management.

   • Select a portfolio from the dropdown list
   • If no portfolios exist, you can create one first
   • You can link or unlink accounts from portfolios at any time
5. (Optional) Switch to the Metadata tab to add custom key-value pairs for additional context or integration purposes.

6. Click the Save button to create the Account.

Field guide

---

Field	What to enter	Example
Account Name	Optional descriptive name for the account. Midaz accepts up to 256 characters and supplies a default name if no name is submitted.	John Doe Checking Account
Account Alias	Unique human-readable identifier. A leading @ is a common convention, not a requirement. This cannot be changed after creation.	@customer_john_checking
Type	Account classification. Required. When Account Type validation is enabled, you select from the predefined Account Types; otherwise you type it freely. This cannot be changed after creation.	customer
External account	Switch available when creating an account. Turn it on to create an external account — the type is set to external automatically and represents balances held outside this ledger.	—
Entity ID	Optional external holder, customer, department, or partner identifier.	customer_123
Asset	Asset this account will use. Select an existing Asset. This cannot be changed after creation.	BRL
Segment	Optional grouping category, available when Segments exist.	Retail
Portfolio	Optional reporting or management group for this Account.	Customer Portfolio
Metadata Key	Optional classification or integration field name.	costCenter
Metadata Value	Value for the metadata key.	BR_11101997

Quick examples

---

Customer Checking Account

Scenario: Create a checking account for a customer.

Field	Value
Account Name	John Doe Checking
Account Alias	@customer_123_checking
Type	checking
Entity ID	customer_123
Asset	USD
Allow Sending	true
Allow Receiving	true

Treasury Account

Scenario: Create a main treasury account for company operations.

Field	Value
Account Name	Main Treasury
Account Alias	@treasury_main
Type	treasury
Entity ID	org_treasury_dept
Asset	USD
Segment	Finance
Allow Sending	true
Allow Receiving	true

Department Budget Account

Scenario: Create a budget account for the engineering department.

Field	Value
Account Name	Engineering Budget 2024
Account Alias	@eng_budget_2024
Type	expense
Entity ID	dept_engineering
Asset	USD
Segment	Engineering
Allow Sending	true
Allow Receiving	true

Important notes

---

Fields that cannot be changed after creation

You cannot change the following fields after you create the account:

• Account Alias - Choose it carefully, because transactions use the alias
• Type - You cannot reclassify it after you set it
• Asset Code - You cannot change the account’s currency or commodity

To change any of these fields, create a new account.

Account Type Validation

If your ledger uses Account Type validation:

• You select the Type from your predefined Account Types instead of typing it freely
• You must select from predefined account types or create them first
• This ensures consistency across your organization’s chart of accounts

See Managing Accounts for more information.

Allow Sending and Allow Receiving

These flags control transaction permissions:

• Allow Sending = false: You cannot use the account as a source (debit side) in transactions
• Allow Receiving = false: You cannot use the account as a destination (credit side) in transactions

Both flags default to on. You can change them only after you create the account. Use these flags to:

• Freeze an account temporarily
• Create a receive-only account (for example, escrow)
• Create a send-only account (rare case)

After you create an account, you can use it in transactions immediately. Make sure all the information is correct before you save, especially the immutable fields.

What to do next

---

After you create the source and destination Accounts:

1. Create or review Accounting Routes in Creating an Accounting Route.
2. Create a Transaction in Creating a Transaction.

API equivalent

Create an Account endpoint