> ## 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
> Model the individuals or organizations behind Midaz accounts as Holders, storing names, documents, contacts, and compliance details as Natural or Legal Person.
A **Holder** is the core entity in CRM. It represents a real-world individual or organization behind a Midaz ledger account. A Holder stores identity attributes such as the name, document number, contact details, and addresses.
[CRM](/en/midaz/crm/crm-overview) manages Holders. Holders do not belong to the ledger's transactional domain. They enrich ledger accounts with business data. They do not affect the ledger's logic, consistency, or performance.
Each Holder is one of two types: **Natural Person** (individual) or **Legal Person** (company/organization).
To create and manage holders step by step, see [Getting started with CRM](/en/midaz/crm/crm-getting-started).
## Holder types
***
The holder type controls which fields are available. It also sets how the platform treats the entity. You choose the type at creation. You **cannot change it later**.
### Natural Person
The Natural Person type represents an individual customer. It supports personal attributes such as the 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
The Legal Person type represents a company or organization. It supports business attributes such as the 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
Choose the holder type carefully at creation. You cannot change it later. To use a different type, create a new Holder.
## 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`). |
| **description** | `string` | No | A descriptive label for the address (for example, Home, Office, or Billing). Max 100 characters. |
### 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
***
Midaz encrypts several Holder fields at rest, including the `name`, the `document`, and the contact fields. This protects the data even if someone gains access to the storage.
Never store sensitive information in the `metadata` object. Midaz does not encrypt metadata and stores it in plain text.
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.
Every CRM API request includes the organization ID in the URL path, for example `/organizations/{organization_id}/holders`. If you enable [Access Manager](/en/platform/access-manager/access-manager), add an `Authorization` header with a Bearer token.
### Via Lerian Console
You can manage Holders through the **Holders** page in the Midaz Module of [Lerian Console](/en/platform/console/about-lerian-console). The console provides a visual interface to create, view, edit, and delete Holders without code.
[**Learn more in the Managing Holders guide.**](/en/midaz/console/managing-crm-holders)
## Next steps
***
Learn how Alias Accounts link Holders to Midaz ledger accounts.
Follow the step-by-step guide to register Holders and create Alias Accounts.