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 the CRM plugin 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).
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
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.
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). |
| 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.
Never store sensitive information in the metadata object. Metadata is not encrypted and is stored in plain text.
Managing Holders
Via API
Use the CRM API to manage Holders programmatically:
All CRM API requests require the X-Organization-Id header. If Access Manager is enabled, an Authorization header with a Bearer token is also required. Via Lerian Console
You can manage Holders through the Holders page in the Midaz Module of 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.
Next steps
