Custom fields

Campos customizados em People, Companies e Deals. Visíveis em GET na v1; definição e escrita feitas pelo app web.

Custom fields permitem estender People, Companies e Deals com campos específicos da sua operação — CPF, NPS último, MRR, segmento ICP, qualquer coisa. Eles vivem em uma coluna jsonb no banco, então não há overhead de schema migration.

Read-only via API v1

A v1 atual expõe custom fields apenas em leitura (eles aparecem em GET junto com os dados do recurso). A definição dos campos e a escrita de valores acontecem pelo app web — o endpoint público de field-definitions não está disponível na v1, e o body de POST/PATCH dos recursos v1 ignora customFields.

Pra escrever em customFields a partir de um sistema externo, use webhooks de entrada — eles aceitam payload arbitrário e mapeiam pra qualquer custom field configurado no workspace.

Modelos suportados

Apenas estes três objetos têm custom fields:

person — pessoas/leads/contatos
company — empresas
deal — negócios

Tipos suportados

Tipo	Validação no app web
`text`	string curta (até 500 chars)
`long_text`	texto longo (sem limite duro)
`number`	número inteiro ou decimal
`currency`	número com moeda associada
`date`	ISO 8601
`select`	uma das opções definidas
`multi_select`	array de opções definidas
`boolean`	`true` / `false`
`email`	string com formato e-mail
`phone`	telefone
`url`	string com formato URL
`relation`	referência a outro registro

Definindo um custom field

Custom fields são definidos no app web em Configurações → Campos customizados:

Escolha o objeto (person, company ou deal).
Defina nome interno (fieldName, imutável depois de criado), label de apresentação, tipo e opções (se select/multi_select).
Salve. O campo aparece imediatamente nos GETs da API e nas telas do app.

O fieldName é o identificador estável usado no payload (customFields.cpf).

Lendo via API

Custom fields aparecem dentro de customFields em todo objeto retornado:

Text

{
  "id": "ad8e3f9b-...",
  "fullName": "Marina Souza",
  "primaryEmail": "marina@acme.com.br",
  "customFields": {
    "cpf": "123.456.789-00",
    "nps_ultimo": 9,
    "icp_segment": "Mid-market",
    "produtos_interesse": ["CRM", "WhatsApp"]
  }
}

Campos não preenchidos vêm como undefined (ausentes do objeto).

Escrevendo a partir do exterior

Você tem duas opções:

Webhook de entrada (guia). Configure um inbound webhook que recebe payload arbitrário e mapeia campos pro workspace — incluindo custom fields.
App web ou automação. Pra atualizações pontuais, use o app web. Pra fluxos repetitivos, automações no-code do MIXY suportam ler/escrever custom fields nativamente.

A v1 da API REST pública vai ganhar suporte a escrita em customFields em versão futura. Acompanhe o changelog.