> ## 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** defines the business context associated with a [Ledger Account](/en/midaz/accounts) in Midaz. It links a [Holder](/en/midaz/crm/holders) 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.

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

<Warning>
  An Alias Account must always be linked to an existing Holder. Create the Holder first, then create the Alias Account. See [Using CRM](/en/midaz/crm/using-crm) 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 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. |

### 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, `endDate` must be after `startDate`.

This allows you to maintain a historical record of who was associated with an account and in what capacity, without discarding past relationships.

#### 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 `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. New entries are **appended** to the existing list — existing related parties are not replaced.
* **Remove** — Use the [Delete Related Party](/en/reference/midaz/crm/delete-related-party) endpoint with the specific `related_party_id`.
* **List** — Related parties are returned as part of the Alias Account response 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

***

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.

<Warning>
  Never store sensitive information in the `metadata` object. Metadata is **not encrypted** and is stored 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>
  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](/en/platform/access-manager/access-manager) is enabled, an `Authorization` header with a Bearer token is also required.
</Note>

### Via Lerian Console

You can manage Alias Accounts through the **Alias Accounts** page in the Midaz Module of [Lerian Console](/en/platform/lerian-console/about-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.**](/en/platform/lerian-console/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 Alias Accounts are linked 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>