# Campos personalizados

> Defina campos personalizados para os seus contatos, preencha os valores pelo painel, por importações e pela API, e use-os em filtros, tags de mesclagem de campanhas e automações.

Os campos personalizados guardam dados extras em cada contato, como o nome de uma empresa, um plano ou uma data de aniversário. Você define os campos uma vez para o workspace, depois os preenche nos contatos e os usa para filtrar contatos, personalizar campanhas e iniciar automações.

## Tipos de campo

| Tipo | Valor armazenado | Exemplo | Entrada no painel |
| --- | --- | --- | --- |
| **Text** | String | `"Acme"` | Caixa de texto |
| **Number** | Número | `42` | Caixa numérica |
| **Date** | Data de calendário, `YYYY-MM-DD` | `"1990-04-12"` | Seletor de data |
| **Boolean** | `true` ou `false` | `true` | Caixa de seleção |
| **Select** | Uma opção | `"pro"` | Lista suspensa |
| **Multi select** | Array de opções | `["news", "offers"]` | Lista suspensa de seleção múltipla |

Cada campo tem um **nome**, que o painel mostra, e uma **chave**, que a API, as importações, os filtros e as tags de mesclagem usam. Os valores são armazenados no contato como um objeto JSON indexado pela chave do campo:

```json
{
  "company": "Acme",
  "plan": "pro",
  "birthday": "1990-04-12",
  "interests": ["news", "offers"]
}
```

## Criar um campo personalizado

1. **Abra Custom fields.** Acesse **Workspace → Settings → Custom fields** e selecione **Add custom field**.

2. **Dê um nome ao campo.** Em **Name**, digite um nome, por exemplo `Company size`. O Emailit monta a chave a partir do nome automaticamente: em minúsculas, com cada sequência de outros caracteres substituída por `_`, então `Company size` vira `company_size`.

   Para escolher a chave você mesmo, selecione **Show advanced options** e edite **Key**. As chaves são sempre salvas nesse formato em minúsculas com sublinhados, e cada chave só pode existir uma vez por workspace.

3. **Escolha o tipo.** Escolha **Text**, **Number**, **Date**, **Boolean**, **Select** ou **Multi select**.

4. **Adicione opções aos campos de seleção.** Em **Select** e **Multi select**, digite pelo menos uma opção e use **Add option** para adicionar mais. Esses valores aparecem na lista suspensa dos contatos.

5. **Salve.** Selecione **Create**. O campo aparece em todos os contatos, nos filtros de contatos e como tag de mesclagem nos editores de campanha.

A página Custom fields lista todos os campos com nome, tipo e opções. Use **Edit** para renomear um campo, alterar o tipo ou a chave dele, ou editar as opções.

> **Excluir um campo:** Excluir um campo personalizado o remove do painel, dos filtros, das importações e das tags de mesclagem, e você não pode desfazer isso. Antes de alterar ou excluir uma chave, atualize todas as campanhas, automações e códigos da API que a usam.

## Definir valores

| Onde | Como |
| --- | --- |
| Painel | **Add contact** ou **Edit** em um contato. Selecione **Show custom fields** para ver os campos. |
| Importação | Associe uma coluna do arquivo ao campo personalizado no assistente de importação. Consulte [Importar e exportar contatos](/pt/docs/contacts/import-export/). |
| API | Envie um objeto `custom_fields` indexado pela chave do campo. |

Pela API, passe `custom_fields` para [Criar um contato](/pt/docs/api-reference/contacts/create/) ou [Atualizar um contato](/pt/docs/api-reference/contacts/update/):

```bash
curl https://api.emailit.com/v2/contacts/ada@example.com \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": {
      "company": "Acme",
      "plan": "pro",
      "birthday": "1990-04-12",
      "interests": ["news", "offers"]
    }
  }'
```

Regras importantes:

- **`custom_fields` substitui o objeto inteiro.** Na atualização, inclua todos os valores que você quer manter, não apenas os que mudam.
- **Use as chaves dos campos, não os nomes.** Os valores de chaves que não estão definidas em **Custom fields** são armazenados, mas não aparecem no painel.
- **As datas precisam estar no formato `YYYY-MM-DD`.** O Emailit converte data e hora ISO e células de data do Excel em uma data. Qualquer outra coisa retorna `400` com “Custom field "Birthday" must be a date in YYYY-MM-DD format”. As datas não têm hora nem fuso horário.
- **Os valores de seleção não são conferidos com as opções.** Um valor que não está na lista de opções é armazenado mesmo assim, e o painel continua a exibi-lo.

## Filtrar contatos por um campo personalizado

No painel, abra **Email Marketing → Contacts**, selecione **Filter** e escolha o campo personalizado pelo nome. Os filtros de campos personalizados comparam o valor armazenado como texto, então use **equals**, **does not equal**, **contains**, **does not contain**, **starts with**, **ends with**, **is empty** ou **is not empty**.

Pela API, use `custom_fields.<key>.<condition>` em [Listar contatos](/pt/docs/api-reference/contacts/list/) e [Exportar contatos](/pt/docs/api-reference/contacts/export/), com as mesmas condições de texto (`exact`, `not_exact`, `contains`, `not_contains`, `starts_with`, `ends_with`, `empty`, `not_empty`):

```bash
curl "https://api.emailit.com/v2/contacts?custom_fields.plan.exact=pro&custom_fields.company.contains=acme" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

Para um intervalo, como aniversários nos anos 1990, use os parâmetros `filter[custom_fields.<key>][gte]` e `[lte]`. Eles comparam o texto armazenado, que fica na ordem correta para datas `YYYY-MM-DD`:

```bash
curl -G "https://api.emailit.com/v2/contacts" \
  --data-urlencode "filter[custom_fields.birthday][gte]=1990-01-01" \
  --data-urlencode "filter[custom_fields.birthday][lte]=1999-12-31" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

Consulte [Filtragem](/pt/docs/api-reference/filtering/) para saber como os filtros se combinam.

## Usar campos personalizados em campanhas

No conteúdo e no assunto das campanhas, insira um campo personalizado com a tag de mesclagem `{{cf.<key>}}`, por exemplo `{{cf.company}}`. Os editores de texto formatado e Dragit listam os seus campos personalizados entre as variáveis, então você não precisa digitar a chave.

```html
<p>Hi {{first_name}}, here's what's new for {{cf.company}}.</p>
```

Se um contato não tiver valor, a tag é substituída por nada. Os valores de seleção múltipla aparecem como uma lista separada por vírgulas. Consulte [Tags de mesclagem](/pt/docs/campaigns/merge-tags/).

## Usar campos personalizados em automações

- **Gatilho de aniversário de data.** Escolha um campo **Date** para iniciar uma execução todo ano no mês e no dia armazenados nele, por exemplo uma data de aniversário. Consulte [Gatilhos](/pt/docs/automations/triggers/#date-anniversary).
- **Gatilho de contato atualizado.** Filtre por um campo personalizado, ou pelo valor anterior dele, para reagir quando ele mudar.
- **Etapa de condição.** Crie ramificações com base no valor de um campo personalizado.
- **Etapa de edição de contato.** Defina um campo personalizado informando a chave dele.

## Referência da API

As definições de campos personalizados são gerenciadas apenas no painel. Os valores dos contatos usam o objeto `custom_fields` na [API de contatos](/pt/docs/api-reference/contacts/), e o mesmo objeto é aceito quando você [adiciona um inscrito](/pt/docs/api-reference/audiences/subscribers/add/) a uma lista.

## Veja também

  - [Contatos](/pt/docs/contacts/): Como contatos, listas e inscritos se encaixam.
  - [Tags de mesclagem](/pt/docs/campaigns/merge-tags/): Personalize campanhas com os dados dos contatos.

---
Fonte: https://emailit.com/pt/docs/contacts/custom-fields/