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 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).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.
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
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
Theaddresses 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 whentype 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 whentype 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
Therepresentative 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. |
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.
For the full list of protected fields and encryption strategies, see CRM data security.
Managing Holders
Via API
Use the CRM API to manage Holders programmatically:- Create a Holder — Register a new Holder in the system.
- List Holders — View all Holders with pagination and filters.
- Retrieve a Holder — Get the details of a specific Holder.
- Update a Holder — Edit an existing Holder’s data.
- Delete a Holder — Soft-delete or permanently remove a Holder.
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
Alias Accounts
Learn how Alias Accounts link Holders to Midaz ledger accounts.
Using CRM
Follow the step-by-step guide to register Holders and create Alias Accounts.