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.
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
| Field | Type | Required | Description |
|---|
| id | uuid | System-generated | Unique identifier of the Alias Account. |
| holderId | uuid | System-generated | The ID of the associated Holder (derived from the URL path). |
| ledgerId | string | Yes | The UUID of the Midaz Ledger. |
| accountId | string | Yes | The UUID of the Midaz Ledger Account. |
| document | string | System-generated | Inherited from the parent Holder. |
| type | string | System-generated | Inherited from the parent Holder (NATURAL_PERSON or LEGAL_PERSON). |
| metadata | object | No | Key-value pairs for custom, non-sensitive data. Keys are limited to 100 characters and values to 2000 characters. |
| createdAt | datetime | System-generated | Timestamp of creation (RFC 3339). |
| updatedAt | datetime | System-generated | Timestamp of last update (RFC 3339). |
| deletedAt | datetime | System-generated | Timestamp of soft deletion, if applicable (RFC 3339). |
Banking details
The bankingDetails object stores financial institution information associated with the alias:
| Field | Type | Required | Description |
|---|
| branch | string | No | Bank branch code (e.g., 0001). |
| account | string | No | Bank account number (e.g., 123450). |
| type | string | No | Account type code (e.g., CACC for current account). |
| openingDate | string | No | Date the account was opened in YYYY-MM-DD format. |
| closingDate | string | No | Date the account was closed, if applicable, in YYYY-MM-DD format. |
| iban | string | No | International Bank Account Number. |
| countryCode | string | No | Country code of the financial institution (e.g., US, BR). |
| bankId | string | No | Identifier of the bank or financial institution. |
Regulatory fields
The regulatoryFields object stores data required by financial regulators:
| Field | Type | Required | Description |
|---|
| participantDocument | string | No | Document number identifying the financial-group entity that owns the relationship. |
relatedParties array defines individuals or entities related to the Alias Account with specific roles. Each entry contains:
| Field | Type | Required | Description |
|---|
| id | uuid | System-generated | Unique identifier of the related party. |
| document | string | Yes | Document number of the related party. |
| name | string | Yes | Full name of the related party. |
| role | enum | Yes | PRIMARY_HOLDER, LEGAL_REPRESENTATIVE, or RESPONSIBLE_PARTY. |
| startDate | string | Yes | Date the party relationship started in YYYY-MM-DD format. |
| endDate | string | No | Date 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.
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
