Alias Accounts

An Alias Account adds business context to a Ledger Account in Midaz. It links a Holder to a specific account in the ledger. It adds banking details, regulatory information, and related-party data to that account. Without this link, CRM features that rely on account context do not work as expected.

​

How it works

---

The Alias Account is a CRM-level representation of a Midaz Ledger Account. When you create an Alias Account, you provide the ledgerId and accountId that identify the target account in the ledger. The Alias Account inherits the document and type from its parent Holder automatically. This design keeps customer-facing account details separate from the transactional ledger. Bank numbers, branch codes, and regulatory identifiers stay in the CRM, not in the ledger. The separation supports multi-bank setups and integration with external systems.

​

Alias Account fields

---

​

Core fields

​

Banking details

The bankingDetails object stores information about the financial institution for the alias:

​

Regulatory fields

The regulatoryFields object stores data that financial regulators require:

​

Related parties

A related party is a person or entity linked to an Alias Account. Each related party has a defined role and a time-bounded relationship. Related parties represent the real-world people or organizations connected to the account, for ownership, legal authority, or operational accountability. Compliance, regulatory reporting, and CRM-driven workflows use them.

​

Roles

Each related party must have one of the following roles:

​

Time-bounded relationships

Every related party relationship has a defined active period:

• startDate — Required. The date the relationship became active (YYYY-MM-DD).
• endDate — Optional. The date the relationship ended (YYYY-MM-DD). If you omit it, the relationship stays active. When you set it, endDate must be after startDate.

This design records who held a relationship with the account, and in what capacity. It keeps past relationships in the record.

​

Managing related parties

You manage related parties through the Alias Account endpoints. There are no standalone create or list endpoints:

• Add on creation — Include a relatedParties array in the Create Alias Account request body.
• Add to existing — Include a relatedParties array in the Update Alias Account request body. Midaz appends new entries to the existing list. It does not replace existing related parties.
• Remove — Use the Delete Related Party endpoint with the specific related_party_id.
• List — The Alias Account response returns related parties in the relatedParties array.

​

Fields

​

Data security

---

Midaz encrypts several Alias Account fields at rest, including the inherited document field and banking details such as account and iban. Encryption protects sensitive financial data even if an attacker reaches the underlying storage. For the full list of protected fields and encryption strategies, see CRM data security.

​

Managing Alias Accounts

---

​

Via API

Use the CRM API to manage Alias Accounts programmatically:

• Create an Alias Account — Link a Holder to a Midaz Ledger Account.
• List Alias Accounts — View all Alias Accounts with pagination and filters.
• Retrieve an Alias Account — Get the details of a specific Alias Account.
• Update an Alias Account — Edit the details of an existing Alias Account.
• Delete an Alias Account — Soft-delete or permanently remove an Alias Account.

​

Via Lerian Console

You can manage Alias Accounts through the Alias Accounts page in the Midaz Module of Lerian Console. The console gives you a visual interface to create, view, edit, and delete Alias Accounts without writing code. Learn more in the Managing Alias Accounts guide.

​

Next steps

---