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

# Holders

> Represent the individuals or organizations behind Midaz accounts, storing identity, contact, and compliance attributes in CRM.

A **Holder** is the core entity in CRM. It represents a real-world individual or organization behind a Midaz ledger account, storing identity-related attributes such as name, document number, contact details, and addresses.

Holders are managed by [CRM](/en/midaz/crm/crm-overview) and don't belong to the ledger's transactional domain. They enrich ledger accounts with business-relevant data without interfering with the ledger's logic, consistency, or performance.

Each Holder is one of two types: **Natural Person** (individual) or **Legal Person** (company/organization).

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

## Holder types

***

The holder type determines which fields are available and how the entity is treated across the platform. It is set at creation and **cannot be changed later**.

### Natural Person

Represents an individual customer. It supports personal attributes such as name, gender, birth date, civil status, nationality, and family information.

Use this type for:

* Individual bank account holders
* Personal wallet owners
* Freelancers or sole proprietors

### Legal Person

Represents a company or organization. It supports business attributes such as trade name, activity type, founding date, company size, and legal representative details.

Use this type for:

* Corporate treasury accounts
* Business partners and suppliers
* Institutional clients

<Tip>
  Choose the holder type carefully at creation. Once set, it cannot be changed — you would need to create a new Holder with the correct type.
</Tip>

## Holder fields

***

### Core fields

| Field          | Type       | Required         | Description                                                                                                       |
| :------------- | :--------- | :--------------- | :---------------------------------------------------------------------------------------------------------------- |
| **id**         | `uuid`     | System-generated | Unique identifier of the Holder.                                                                                  |
| **type**       | `enum`     | Yes              | `NATURAL_PERSON` or `LEGAL_PERSON`.                                                                               |
| **name**       | `string`   | Yes              | Full name of the individual or legal name of the company.                                                         |
| **document**   | `string`   | Yes              | Identification document number (e.g., CPF, CNPJ, passport).                                                       |
| **externalId** | `string`   | No               | Optional identifier to map the Holder to an external system.                                                      |
| **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).                                                             |

### Address fields

The `addresses` object supports up to three addresses: `primary`, `additional1`, and `additional2`. Each address contains:

| Field       | Type     | Required | Description                                                    |
| :---------- | :------- | :------- | :------------------------------------------------------------- |
| **line1**   | `string` | Yes      | Primary address line (street, number). Max 256 characters.     |
| **line2**   | `string` | No       | Secondary address line (apartment, suite). Max 256 characters. |
| **zipCode** | `string` | Yes      | Postal or ZIP code. Max 20 characters.                         |
| **city**    | `string` | Yes      | City name. Max 100 characters.                                 |
| **state**   | `string` | Yes      | State or province code. Max 100 characters.                    |
| **country** | `string` | Yes      | ISO 3166-1 alpha-2 country code (e.g., `US`, `BR`).            |

### Contact fields

| Field              | Type     | Required | Description                                                     |
| :----------------- | :------- | :------- | :-------------------------------------------------------------- |
| **primaryEmail**   | `string` | No       | Primary email address.                                          |
| **secondaryEmail** | `string` | No       | Secondary email address.                                        |
| **mobilePhone**    | `string` | No       | Mobile phone number with country code (e.g., `+5511999999999`). |
| **otherPhone**     | `string` | No       | Alternative phone number.                                       |

### Natural Person fields

Available only when `type` is `NATURAL_PERSON`.

| Field            | Type     | Required | Description                                                           |
| :--------------- | :------- | :------- | :-------------------------------------------------------------------- |
| **favoriteName** | `string` | No       | Preferred name or nickname.                                           |
| **socialName**   | `string` | No       | Social name (name the person identifies with).                        |
| **gender**       | `string` | No       | Gender identity.                                                      |
| **birthDate**    | `string` | No       | Date of birth in `YYYY-MM-DD` format.                                 |
| **civilStatus**  | `string` | No       | Marital status (e.g., Single, Married, Divorced).                     |
| **nationality**  | `string` | No       | Nationality (e.g., Brazilian, American).                              |
| **motherName**   | `string` | No       | Mother's full name.                                                   |
| **fatherName**   | `string` | No       | Father's full name.                                                   |
| **status**       | `string` | No       | Lifecycle status (e.g., `Active`, `Inactive`, `Suspended`, `Closed`). |

### Legal Person fields

Available only when `type` is `LEGAL_PERSON`.

| Field            | Type     | Required | Description                                                           |
| :--------------- | :------- | :------- | :-------------------------------------------------------------------- |
| **tradeName**    | `string` | No       | Trade or doing-business-as name.                                      |
| **activity**     | `string` | No       | Primary business activity.                                            |
| **type**         | `string` | No       | Legal structure (e.g., LLC, Corporation).                             |
| **foundingDate** | `string` | No       | Date the company was founded in `YYYY-MM-DD` format.                  |
| **size**         | `string` | No       | Company size classification (e.g., Small, Medium, Large).             |
| **status**       | `string` | No       | Lifecycle status (e.g., `Active`, `Inactive`, `Suspended`, `Closed`). |

#### Representative

The `representative` object within `legalPerson` stores the details of the company's legal representative:

| Field        | Type     | Required | Description                               |
| :----------- | :------- | :------- | :---------------------------------------- |
| **name**     | `string` | No       | Full name of the legal representative.    |
| **document** | `string` | No       | Document number of the representative.    |
| **email**    | `string` | No       | Email address of the representative.      |
| **role**     | `string` | No       | Role within the company (e.g., CEO, CFO). |

## Data security

***

Several Holder fields are **encrypted at rest** using AES encryption, including `name`, `document`, and contact information. This ensures that sensitive personal 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 Holders

***

### Via API

Use the CRM API to manage Holders programmatically:

* [Create a Holder](/en/reference/midaz/crm/create-holder) — Register a new Holder in the system.
* [List Holders](/en/reference/midaz/crm/list-holders) — View all Holders with pagination and filters.
* [Retrieve a Holder](/en/reference/midaz/crm/retrieve-holder) — Get the details of a specific Holder.
* [Update a Holder](/en/reference/midaz/crm/update-holder) — Edit an existing Holder's data.
* [Delete a Holder](/en/reference/midaz/crm/delete-holder) — Soft-delete or permanently remove a Holder.

<Note>
  All CRM API requests require the `X-Organization-Id` header. 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 Holders through the **Holders** 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 Holders without writing code.

[**Learn more in the Managing Holders guide.**](/en/platform/lerian-console/midaz-console/managing-crm-holders)

## Next steps

***

<CardGroup cols={2}>
  <Card title="Alias Accounts" icon="link" href="/en/midaz/crm/alias-accounts">
    Learn how Alias Accounts link Holders to Midaz ledger accounts.
  </Card>

  <Card title="Using CRM" icon="rocket" href="/en/midaz/crm/using-crm">
    Follow the step-by-step guide to register Holders and create Alias Accounts.
  </Card>
</CardGroup>