> ## 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.
# Titulares
> Modele as pessoas físicas ou organizações por trás das contas do Midaz como Titulares, guardando nomes, documentos, contatos e detalhes de compliance como Pessoa Física ou Pessoa Jurídica.
Um **Titular** é a entidade principal do CRM. Ele representa uma pessoa física ou organização do mundo real por trás de uma conta do ledger do Midaz. Um Titular guarda atributos de identidade como o nome, o número do documento, os dados de contato e os endereços.
O [CRM](/pt/products/midaz/crm/crm-overview) gerencia os Titulares. Os Titulares não pertencem ao domínio transacional do ledger. Eles enriquecem as contas do ledger com dados de negócio. Não afetam a lógica, a consistência nem o desempenho do ledger.
Cada Titular é de um dos dois tipos: **Pessoa Física** (indivíduo) ou **Pessoa Jurídica** (empresa/organização).
Para criar e gerenciar titulares passo a passo, veja [Primeiros passos com o CRM](/pt/products/midaz/crm/crm-getting-started).
## Tipos de titular
***
O tipo de titular controla quais campos ficam disponíveis. Ele também define como a plataforma trata a entidade. Você escolhe o tipo na criação. Você **não pode alterá-lo depois**.
### Pessoa Física
O tipo Pessoa Física representa um cliente indivíduo. Ele aceita atributos pessoais como o nome, o gênero, a data de nascimento, o estado civil, a nacionalidade e informações familiares.
Use este tipo para:
* Titulares individuais de conta bancária
* Donos de carteira pessoal
* Freelancers ou empresários individuais
### Pessoa Jurídica
O tipo Pessoa Jurídica representa uma empresa ou organização. Ele aceita atributos de negócio como o nome fantasia, o tipo de atividade, a data de fundação, o porte da empresa e os detalhes do representante legal.
Use este tipo para:
* Contas de tesouraria corporativa
* Parceiros de negócio e fornecedores
* Clientes institucionais
Escolha o tipo de titular com cuidado na criação. Você não pode alterá-lo depois. Para usar um tipo diferente, crie um novo Titular.
## Campos do titular
***
### Campos principais
| Campo | Tipo | Obrigatório | Descrição |
| :------------- | :--------- | :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------- |
| **id** | `uuid` | Gerado pelo sistema | Identificador único do Titular. |
| **type** | `enum` | Sim | `NATURAL_PERSON` ou `LEGAL_PERSON`. |
| **name** | `string` | Sim | Nome completo do indivíduo ou razão social da empresa. |
| **document** | `string` | Sim | Número do documento de identificação (por exemplo, CPF, CNPJ, passaporte). |
| **externalId** | `string` | Não | Identificador opcional para mapear o Titular a um sistema externo. |
| **metadata** | `object` | Não | Pares chave-valor para dados personalizados e não sensíveis. As chaves ficam limitadas a 100 caracteres e os valores, a 2000 caracteres. |
| **createdAt** | `datetime` | Gerado pelo sistema | Timestamp de criação (RFC 3339). |
| **updatedAt** | `datetime` | Gerado pelo sistema | Timestamp da última atualização (RFC 3339). |
| **deletedAt** | `datetime` | Gerado pelo sistema | Timestamp da exclusão reversível, se aplicável (RFC 3339). |
### Campos de endereço
O objeto `addresses` aceita até três endereços: `primary`, `additional1` e `additional2`. Cada endereço contém:
| Campo | Tipo | Obrigatório | Descrição |
| :-------------- | :------- | :---------- | :---------------------------------------------------------------------------------------------------------- |
| **line1** | `string` | Sim | Linha principal do endereço (rua, número). Máximo de 256 caracteres. |
| **line2** | `string` | Não | Linha secundária do endereço (apartamento, sala). Máximo de 256 caracteres. |
| **zipCode** | `string` | Sim | CEP ou código postal. Máximo de 20 caracteres. |
| **city** | `string` | Sim | Nome da cidade. Máximo de 100 caracteres. |
| **state** | `string` | Sim | Código do estado ou província. Máximo de 100 caracteres. |
| **country** | `string` | Sim | Código de país ISO 3166-1 alpha-2 (por exemplo, `US`, `BR`). |
| **description** | `string` | Não | Um rótulo descritivo para o endereço (por exemplo, Casa, Escritório ou Cobrança). Máximo de 100 caracteres. |
### Campos de contato
| Campo | Tipo | Obrigatório | Descrição |
| :----------------- | :------- | :---------- | :-------------------------------------------------------------------- |
| **primaryEmail** | `string` | Não | Endereço de e-mail principal. |
| **secondaryEmail** | `string` | Não | Endereço de e-mail secundário. |
| **mobilePhone** | `string` | Não | Número de celular com código do país (por exemplo, `+5511999999999`). |
| **otherPhone** | `string` | Não | Número de telefone alternativo. |
### Campos de Pessoa Física
Disponíveis apenas quando `type` é `NATURAL_PERSON`.
| Campo | Tipo | Obrigatório | Descrição |
| :--------------- | :------- | :---------- | :---------------------------------------------------------------------------------- |
| **favoriteName** | `string` | Não | Nome preferido ou apelido. |
| **socialName** | `string` | Não | Nome social (nome com o qual a pessoa se identifica). |
| **gender** | `string` | Não | Identidade de gênero. |
| **birthDate** | `string` | Não | Data de nascimento no formato `YYYY-MM-DD`. |
| **civilStatus** | `string` | Não | Estado civil (por exemplo, Solteiro, Casado, Divorciado). |
| **nationality** | `string` | Não | Nacionalidade (por exemplo, Brasileira, Americana). |
| **motherName** | `string` | Não | Nome completo da mãe. |
| **fatherName** | `string` | Não | Nome completo do pai. |
| **status** | `string` | Não | Status do ciclo de vida (por exemplo, `Active`, `Inactive`, `Suspended`, `Closed`). |
### Campos de Pessoa Jurídica
Disponíveis apenas quando `type` é `LEGAL_PERSON`.
| Campo | Tipo | Obrigatório | Descrição |
| :--------------- | :------- | :---------- | :---------------------------------------------------------------------------------- |
| **tradeName** | `string` | Não | Nome fantasia. |
| **activity** | `string` | Não | Atividade principal do negócio. |
| **type** | `string` | Não | Estrutura jurídica (por exemplo, LLC, Corporation). |
| **foundingDate** | `string` | Não | Data de fundação da empresa no formato `YYYY-MM-DD`. |
| **size** | `string` | Não | Classificação de porte da empresa (por exemplo, Pequena, Média, Grande). |
| **status** | `string` | Não | Status do ciclo de vida (por exemplo, `Active`, `Inactive`, `Suspended`, `Closed`). |
#### Representante
O objeto `representative` dentro de `legalPerson` guarda os detalhes do representante legal da empresa:
| Campo | Tipo | Obrigatório | Descrição |
| :----------- | :------- | :---------- | :----------------------------------------------- |
| **name** | `string` | Não | Nome completo do representante legal. |
| **document** | `string` | Não | Número do documento do representante. |
| **email** | `string` | Não | Endereço de e-mail do representante. |
| **role** | `string` | Não | Cargo dentro da empresa (por exemplo, CEO, CFO). |
## Segurança de dados
***
O Midaz criptografa vários campos do Titular em repouso, incluindo o `name`, o `document` e os campos de contato. Isso protege os dados mesmo que alguém obtenha acesso ao armazenamento.
Nunca guarde informações sensíveis no objeto `metadata`. O Midaz não criptografa metadados e os guarda em texto simples.
Para a lista completa de campos protegidos e estratégias de criptografia, veja [Segurança de dados do CRM](/pt/products/midaz/crm/crm-data-security).
## Gerenciando Titulares
***
### Via API
Use a API do CRM para gerenciar Titulares de forma programática:
* [Criar um Titular](/pt/reference/products/midaz/v2/create-holder): registre um novo Titular no sistema.
* [Listar Titulares](/pt/reference/products/midaz/v2/list-holders): veja todos os Titulares com paginação e filtros.
* [Recuperar um Titular](/pt/reference/products/midaz/v2/get-holder-by-id): obtenha os detalhes de um Titular específico.
* [Atualizar um Titular](/pt/reference/products/midaz/v2/update-holder): edite os dados de um Titular existente.
* [Excluir um Titular](/pt/reference/products/midaz/v2/delete-holder): faça a exclusão reversível ou remova um Titular permanentemente.
Toda requisição à API do CRM inclui o ID da organização no caminho da URL, por exemplo `/organizations/{organization_id}/holders`. Se você habilitar o [Access Manager](/pt/platform/access-manager), adicione um cabeçalho `Authorization` com um token Bearer.
### Via Lerian Console
Você pode gerenciar Titulares pela página **Titulares** no Módulo Midaz do [Lerian Console](/pt/platform/console/about-lerian-console). O console permite criar, ver, editar e excluir Titulares sem código.
[**Saiba mais no guia Gerenciando Titulares.**](/pt/products/midaz/console/managing-crm-holders)
## Próximos passos
***
Aprenda como as Contas Alias vinculam Titulares a contas do ledger do Midaz.
Siga o guia passo a passo para cadastrar Titulares e criar Contas Alias.