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.
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
ThebankingDetails 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
TheregulatoryFields 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. |
Related parties
Related parties are individuals or entities associated with an Alias Account that have a defined role and a time-bounded relationship. They represent the real-world people or organizations connected to the account — whether for ownership, legal authority, or operational accountability — and are used in compliance, regulatory reporting, and CRM-driven workflows.Roles
Each related party must have one of the following roles:| Role | Description |
|---|---|
PRIMARY_HOLDER | The main individual or entity who owns or holds the account. This is typically the customer themselves when account ownership differs from the Holder record. |
LEGAL_REPRESENTATIVE | Someone with legal authority to act on behalf of the holder — for example, a legal guardian, attorney, or authorized representative. |
RESPONSIBLE_PARTY | An entity responsible for the account in an operational or regulatory capacity, such as a compliance officer or a parent organization. |
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 omitted, the relationship is considered currently active. When provided,endDatemust be afterstartDate.
Managing related parties
Related parties are managed through the Alias Account endpoints — there are no standalone create or list endpoints:- Add on creation — Include a
relatedPartiesarray in the Create Alias Account request body. - Add to existing — Include a
relatedPartiesarray in the Update Alias Account request body. New entries are appended to the existing list — existing related parties are not replaced. - Remove — Use the Delete Related Party endpoint with the specific
related_party_id. - List — Related parties are returned as part of the Alias Account response in the
relatedPartiesarray.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
| id | uuid | System-generated | Unique identifier of the related party. |
| document | string | Yes | Document number of the related party. Cannot be empty or whitespace. |
| name | string | Yes | Full name of the related party. Cannot be empty or whitespace. |
| 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. Must be after startDate when provided. |
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.
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.
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.