> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Alias Accounts

> Link Holders to Midaz Ledger Accounts with Alias Accounts, adding banking, regulatory, and related-party context for CRM-driven features.

An **Alias Account** adds business context to a [Ledger Account](/en/midaz/accounts) in Midaz. It links a [Holder](/en/midaz/crm/holders) 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.

<Tip>
  For a step-by-step walkthrough of linking holders to accounts, see [Getting started with CRM](/en/midaz/crm/crm-getting-started).
</Tip>

## 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.

<Warning>
  Always link an Alias Account to an existing Holder. Create the Holder first, then create the Alias Account. See [Using CRM](/en/midaz/crm/crm-using-overview) for the correct integration flow.
</Warning>

## 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 information about the financial institution for 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 that financial regulators require:

| Field                   | Type     | Required | Description                                                                        |
| :---------------------- | :------- | :------- | :--------------------------------------------------------------------------------- |
| **participantDocument** | `string` | No       | Document number identifying the financial-group entity that owns the relationship. |

### 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:

| 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 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](/en/reference/midaz/crm/create-alias-account) request body.
* **Add to existing** — Include a `relatedParties` array in the [Update Alias Account](/en/reference/midaz/crm/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](/en/reference/midaz/crm/delete-related-party) endpoint with the specific `related_party_id`.
* **List** — The Alias Account response returns related parties in the `relatedParties` array.

#### 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. |

<Warning>
  Validation errors for related party fields return specific error codes: **CRM-0025** (invalid role), **CRM-0026** (document required), **CRM-0027** (name required), **CRM-0028** (start date required), **CRM-0029** (end date invalid — must be after start date). See the [CRM error reference](/en/reference/midaz/crm/crm-error-list) for details.
</Warning>

## 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.

<Warning>
  Never store sensitive information in the `metadata` object. Midaz does **not** encrypt metadata, and stores it in plain text.
</Warning>

For the full list of protected fields and encryption strategies, see [CRM data security](/en/midaz/crm/crm-data-security).

## Managing Alias Accounts

***

### Via API

Use the CRM API to manage Alias Accounts programmatically:

* [Create an Alias Account](/en/reference/midaz/crm/create-alias-account) — Link a Holder to a Midaz Ledger Account.
* [List Alias Accounts](/en/reference/midaz/crm/list-alias-accounts) — View all Alias Accounts with pagination and filters.
* [Retrieve an Alias Account](/en/reference/midaz/crm/retrieve-alias-account) — Get the details of a specific Alias Account.
* [Update an Alias Account](/en/reference/midaz/crm/update-alias-account) — Edit the details of an existing Alias Account.
* [Delete an Alias Account](/en/reference/midaz/crm/delete-alias-account) — Soft-delete or permanently remove an Alias Account.

<Note>
  The organization ID is a URL path parameter for every Alias Account operation. The Holder ID is a path parameter for most of them. If [Access Manager](/en/platform/access-manager/access-manager) is enabled, add an `Authorization` header with a Bearer token.
</Note>

### Via Lerian Console

You can manage Alias Accounts through the **Alias Accounts** page in the Midaz Module of [Lerian Console](/en/platform/console/about-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.**](/en/midaz/console/managing-crm-alias-accounts)

## Next steps

***

<CardGroup cols={2}>
  <Card title="Holders" icon="user" href="/en/midaz/crm/holders">
    Learn about the Holder entity that an Alias Account links to.
  </Card>

  <Card title="Best practices" icon="check" href="/en/midaz/crm/crm-best-practices">
    Review operational and data management best practices for CRM.
  </Card>
</CardGroup>