Skip to main content
An Alias Account defines the business context associated with a Ledger Account in Midaz. It links a Holder to a specific account in the ledger, enriching it with banking details, regulatory information, and related party data. Without this connection, most CRM-driven features — such as fees, notifications, and billing — won’t work as expected.
For a step-by-step walkthrough of linking holders to accounts, see Getting started with CRM.

​
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 then inherits the document and type from its parent Holder automatically. This design keeps customer-facing account information (bank numbers, branch codes, regulatory identifiers) separate from the transactional ledger, giving you flexibility for multi-bank scenarios and external system integration.
An Alias Account must always be linked to an existing Holder. Create the Holder first, then create the Alias Account. See Using CRM for the correct integration flow.

​
Alias Account fields

​
Core fields

FieldTypeRequiredDescription
iduuidSystem-generatedUnique identifier of the Alias Account.
holderIduuidSystem-generatedThe ID of the associated Holder (derived from the URL path).
ledgerIdstringYesThe UUID of the Midaz Ledger.
accountIdstringYesThe UUID of the Midaz Ledger Account.
documentstringSystem-generatedInherited from the parent Holder.
typestringSystem-generatedInherited from the parent Holder (NATURAL_PERSON or LEGAL_PERSON).
metadataobjectNoKey-value pairs for custom, non-sensitive data. Keys are limited to 100 characters and values to 2000 characters.
createdAtdatetimeSystem-generatedTimestamp of creation (RFC 3339).
updatedAtdatetimeSystem-generatedTimestamp of last update (RFC 3339).
deletedAtdatetimeSystem-generatedTimestamp of soft deletion, if applicable (RFC 3339).

​
Banking details

The bankingDetails object stores financial institution information associated with the alias:
FieldTypeRequiredDescription
branchstringNoBank branch code (e.g., 0001).
accountstringNoBank account number (e.g., 123450).
typestringNoAccount type code (e.g., CACC for current account).
openingDatestringNoDate the account was opened in YYYY-MM-DD format.
closingDatestringNoDate the account was closed, if applicable, in YYYY-MM-DD format.
ibanstringNoInternational Bank Account Number.
countryCodestringNoCountry code of the financial institution (e.g., US, BR).
bankIdstringNoIdentifier of the bank or financial institution.

​
Regulatory fields

The regulatoryFields object stores data required by financial regulators:
FieldTypeRequiredDescription
participantDocumentstringNoDocument number identifying the financial-group entity that owns the relationship.
The relatedParties array defines individuals or entities related to the Alias Account with specific roles. Each entry contains:
FieldTypeRequiredDescription
iduuidSystem-generatedUnique identifier of the related party.
documentstringYesDocument number of the related party.
namestringYesFull name of the related party.
roleenumYesPRIMARY_HOLDER, LEGAL_REPRESENTATIVE, or RESPONSIBLE_PARTY.
startDatestringYesDate the party relationship started in YYYY-MM-DD format.
endDatestringNoDate the party relationship ended, if applicable.
Related parties can be added when creating or updating an Alias Account. To remove a specific related party, use the dedicated Delete Related Party endpoint.

​
Data security

Several Alias Account fields are encrypted at rest, including the inherited document field and banking details such as account and iban. This ensures that sensitive financial data is protected even if the underlying storage is compromised.
Never store sensitive information in the metadata object. Metadata is not encrypted and is stored in plain text.
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:
All CRM API requests require the X-Organization-Id header. The Holder ID is part of the URL path for most Alias Account operations. If Access Manager is enabled, an Authorization header with a Bearer token is also required.

​
Via Lerian Console

You can manage Alias Accounts through the Alias Accounts page in the Midaz Module of Lerian Console. The console provides a visual interface for creating, viewing, editing, and deleting Alias Accounts without writing code. Learn more in the Managing Alias Accounts guide.

​
Next steps

Holders

Learn about the Holder entity that Alias Accounts are linked to.

Best practices

Review operational and data management best practices for CRM.