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

> Representa a personas u organizaciones detrás de las cuentas Midaz, almacenando identidad, contacto y atributos de cumplimiento en el CRM.

Un **Holder** es la entidad principal en CRM. Representa a un individuo u organización del mundo real detrás de una cuenta del ledger en Midaz. Un Holder almacena atributos de identidad como el nombre, el número de documento, los datos de contacto y las direcciones.

[CRM](/es/midaz/crm/crm-overview) gestiona los Holders. Los Holders no pertenecen al dominio transaccional del ledger. Enriquecen las cuentas del ledger con datos de negocio. No afectan la lógica, la consistencia ni el rendimiento del ledger.

Cada Holder es de uno de dos tipos: **Persona Natural** (Natural Person) o **Persona Jurídica** (Legal Person).

<Tip>
  Para crear y gestionar holders paso a paso, consulta [Primeros pasos con CRM](/es/midaz/crm/crm-getting-started).
</Tip>

## Tipos de Holder

***

El tipo de holder controla qué campos están disponibles. También define cómo la plataforma trata la entidad. Eliges el tipo al momento de la creación. **No puedes cambiarlo después**.

### Persona Natural (Natural Person)

El tipo Persona Natural representa a un cliente individual. Soporta atributos personales como el nombre, el género, la fecha de nacimiento, el estado civil, la nacionalidad y la información familiar.

Usa este tipo para:

* Titulares de cuentas bancarias individuales
* Propietarios de billeteras personales
* Trabajadores independientes o autónomos

### Persona Jurídica (Legal Person)

El tipo Persona Jurídica representa a una empresa u organización. Soporta atributos empresariales como el nombre comercial, el tipo de actividad, la fecha de fundación, el tamaño de la empresa y los detalles del representante legal.

Usa este tipo para:

* Cuentas de tesorería corporativa
* Socios comerciales y proveedores
* Clientes institucionales

<Tip>
  Elige el tipo de holder con cuidado al momento de la creación. No puedes cambiarlo después. Para usar un tipo diferente, crea un nuevo Holder.
</Tip>

## Campos del Holder

***

### Campos principales

| Campo          | Tipo       | Requerido               | Descripción                                                                                                                |
| :------------- | :--------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| **id**         | `uuid`     | Generado por el sistema | Identificador único del Holder.                                                                                            |
| **type**       | `enum`     | Sí                      | `NATURAL_PERSON` o `LEGAL_PERSON`.                                                                                         |
| **name**       | `string`   | Sí                      | Nombre completo del individuo o razón social de la empresa.                                                                |
| **document**   | `string`   | Sí                      | Número del documento de identificación (ej.: CPF, CNPJ, pasaporte).                                                        |
| **externalId** | `string`   | No                      | Identificador opcional para mapear el Holder a un sistema externo.                                                         |
| **metadata**   | `object`   | No                      | Pares clave-valor para datos personalizados y no sensibles. Claves limitadas a 100 caracteres y valores a 2000 caracteres. |
| **createdAt**  | `datetime` | Generado por el sistema | Timestamp de creación (RFC 3339).                                                                                          |
| **updatedAt**  | `datetime` | Generado por el sistema | Timestamp de última actualización (RFC 3339).                                                                              |
| **deletedAt**  | `datetime` | Generado por el sistema | Timestamp de eliminación lógica, si aplica (RFC 3339).                                                                     |

### Campos de dirección

El objeto `addresses` soporta hasta tres direcciones: `primary`, `additional1` y `additional2`. Cada dirección contiene:

| Campo           | Tipo     | Requerido | Descripción                                                                                            |
| :-------------- | :------- | :-------- | :----------------------------------------------------------------------------------------------------- |
| **line1**       | `string` | Sí        | Línea principal de dirección (calle, número). Máx. 256 caracteres.                                     |
| **line2**       | `string` | No        | Línea secundaria de dirección (apartamento, oficina). Máx. 256 caracteres.                             |
| **zipCode**     | `string` | Sí        | Código postal. Máx. 20 caracteres.                                                                     |
| **city**        | `string` | Sí        | Nombre de la ciudad. Máx. 100 caracteres.                                                              |
| **state**       | `string` | Sí        | Estado o provincia. Máx. 100 caracteres.                                                               |
| **country**     | `string` | Sí        | Código de país ISO 3166-1 alpha-2 (ej.: `US`, `BR`).                                                   |
| **description** | `string` | No        | Una etiqueta descriptiva para la dirección (por ejemplo, Home, Office o Billing). Máx. 100 caracteres. |

### Campos de contacto

| Campo              | Tipo     | Requerido | Descripción                                                          |
| :----------------- | :------- | :-------- | :------------------------------------------------------------------- |
| **primaryEmail**   | `string` | No        | Dirección de correo electrónico principal.                           |
| **secondaryEmail** | `string` | No        | Dirección de correo electrónico secundaria.                          |
| **mobilePhone**    | `string` | No        | Número de teléfono móvil con código de país (ej.: `+5511999999999`). |
| **otherPhone**     | `string` | No        | Número de teléfono alternativo.                                      |

### Campos de Persona Natural

Disponibles solo cuando `type` es `NATURAL_PERSON`.

| Campo            | Tipo     | Requerido | Descripción                                                                  |
| :--------------- | :------- | :-------- | :--------------------------------------------------------------------------- |
| **favoriteName** | `string` | No        | Nombre preferido o apodo.                                                    |
| **socialName**   | `string` | No        | Nombre social (nombre con el que la persona se identifica).                  |
| **gender**       | `string` | No        | Identidad de género.                                                         |
| **birthDate**    | `string` | No        | Fecha de nacimiento en formato `AAAA-MM-DD`.                                 |
| **civilStatus**  | `string` | No        | Estado civil (ej.: Soltero, Casado, Divorciado).                             |
| **nationality**  | `string` | No        | Nacionalidad (ej.: Brasileño, Estadounidense).                               |
| **motherName**   | `string` | No        | Nombre completo de la madre.                                                 |
| **fatherName**   | `string` | No        | Nombre completo del padre.                                                   |
| **status**       | `string` | No        | Estado del ciclo de vida (ej.: `Active`, `Inactive`, `Suspended`, `Closed`). |

### Campos de Persona Jurídica

Disponibles solo cuando `type` es `LEGAL_PERSON`.

| Campo            | Tipo     | Requerido | Descripción                                                                  |
| :--------------- | :------- | :-------- | :--------------------------------------------------------------------------- |
| **tradeName**    | `string` | No        | Nombre comercial de la empresa.                                              |
| **activity**     | `string` | No        | Actividad principal de la empresa.                                           |
| **type**         | `string` | No        | Estructura legal (ej.: SRL, S.A.).                                           |
| **foundingDate** | `string` | No        | Fecha de fundación de la empresa en formato `AAAA-MM-DD`.                    |
| **size**         | `string` | No        | Clasificación del tamaño de la empresa (ej.: Pequeña, Mediana, Grande).      |
| **status**       | `string` | No        | Estado del ciclo de vida (ej.: `Active`, `Inactive`, `Suspended`, `Closed`). |

#### Representante

El objeto `representative` dentro de `legalPerson` almacena los detalles del representante legal de la empresa:

| Campo        | Tipo     | Requerido | Descripción                                        |
| :----------- | :------- | :-------- | :------------------------------------------------- |
| **name**     | `string` | No        | Nombre completo del representante legal.           |
| **document** | `string` | No        | Número de documento del representante.             |
| **email**    | `string` | No        | Dirección de correo electrónico del representante. |
| **role**     | `string` | No        | Cargo dentro de la empresa (ej.: CEO, CFO).        |

## Seguridad de los datos

***

Midaz cifra varios campos del Holder en reposo, incluidos `name`, `document` y los campos de contacto. Esto protege los datos incluso si alguien accede al almacenamiento.

<Warning>
  Nunca almacenes información sensible en el objeto `metadata`. Midaz no cifra los metadatos y los almacena en texto plano.
</Warning>

Para la lista completa de campos protegidos y estrategias de cifrado, consulta [Seguridad de datos del CRM](/es/midaz/crm/crm-data-security).

## Gestionando Holders

***

### Vía API

Usa la API del CRM para gestionar Holders programáticamente:

* [Crear un Holder](/es/reference/midaz/crm/create-holder) — Registrar un nuevo Holder en el sistema.
* [Listar Holders](/es/reference/midaz/crm/list-holders) — Ver todos los Holders con paginación y filtros.
* [Consultar un Holder](/es/reference/midaz/crm/retrieve-holder) — Obtener los detalles de un Holder específico.
* [Actualizar un Holder](/es/reference/midaz/crm/update-holder) — Editar los datos de un Holder existente.
* [Eliminar un Holder](/es/reference/midaz/crm/delete-holder) — Eliminar lógicamente o remover permanentemente un Holder.

<Note>
  Cada solicitud a la API del CRM incluye el ID de la organización en la ruta de la URL, por ejemplo `/organizations/{organization_id}/holders`. Si habilitas [Access Manager](/es/platform/access-manager/access-manager), agrega un header `Authorization` con un token Bearer.
</Note>

### Vía Lerian Console

Puedes gestionar Holders a través de la página **Holders** en el Módulo Midaz de [Lerian Console](/es/platform/console/about-lerian-console). La consola ofrece una interfaz visual para crear, ver, editar y eliminar Holders sin código.

[**Aprende más en la guía de Gestión de Holders.**](/es/midaz/console/managing-crm-holders)

## Próximos pasos

***

<CardGroup cols={2}>
  <Card title="Alias Accounts" icon="link" href="/es/midaz/crm/alias-accounts">
    Aprende cómo las Alias Accounts vinculan Holders a cuentas del Ledger en Midaz.
  </Card>

  <Card title="Usando CRM" icon="rocket" href="/es/midaz/crm/crm-using-overview">
    Sigue la guía paso a paso para registrar Holders y crear Alias Accounts.
  </Card>
</CardGroup>