Holders

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

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.

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.

Every CRM API request includes the organization ID in the URL path, for example /organizations/{organization_id}/holders. If you enable 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. The console provides a visual interface to create, view, edit, and delete Holders without code. Learn more in the Managing Holders guide.

Midaz Core

CRM

Fees

Holder types

Natural Person

Legal Person

Holder fields

Core fields

Address fields

Contact fields

Natural Person fields

Legal Person fields

Representative

Data security

Managing Holders

Via API

Via Lerian Console

Next steps

Alias Accounts

Using CRM

​Holder types

​Natural Person

​Legal Person

​Holder fields

​Core fields

​Address fields

​Contact fields

​Natural Person fields

​Legal Person fields

​Representative

​Data security

​Managing Holders

​Via API

​Via Lerian Console

​Next steps

Alias Accounts

Using CRM

Holder types

Natural Person

Legal Person

Holder fields

Core fields

Address fields

Contact fields

Natural Person fields

Legal Person fields

Representative

Data security

Managing Holders

Via API

Via Lerian Console

Next steps