# Campi personalizzati

> Definisci i campi personalizzati dei contatti, impostane i valori dal pannello, con le importazioni e con l’API, e usali nei filtri, nei tag di unione delle campagne e nelle automazioni.

I campi personalizzati memorizzano dati aggiuntivi su ogni contatto, come il nome di un’azienda, un piano o un compleanno. Definisci i campi una volta per il workspace, poi li compili sui contatti e li usi per filtrare i contatti, personalizzare le campagne e avviare le automazioni.

## Tipi di campo

| Tipo | Valore memorizzato | Esempio | Input nel pannello |
| --- | --- | --- | --- |
| **Text** | Stringa | `"Acme"` | Casella di testo |
| **Number** | Numero | `42` | Casella numerica |
| **Date** | Data di calendario, `YYYY-MM-DD` | `"1990-04-12"` | Selettore di data |
| **Boolean** | `true` o `false` | `true` | Casella di spunta |
| **Select** | Un’opzione | `"pro"` | Menu a tendina |
| **Multi select** | Array di opzioni | `["news", "offers"]` | Menu a tendina a selezione multipla |

Ogni campo ha un **nome**, che il pannello mostra, e una **chiave**, che usano l’API, le importazioni, i filtri e i tag di unione. I valori vengono memorizzati sul contatto come oggetto JSON indicizzato per chiave del campo:

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

## Crea un campo personalizzato

1. **Apri Custom fields.** Vai a **Workspace → Settings → Custom fields** e seleziona **Add custom field**.

2. **Dai un nome al campo.** Compila il campo **Name**, ad esempio `Company size`. Emailit ricava automaticamente la chiave dal nome: in minuscolo, con ogni sequenza di altri caratteri sostituita da `_`, quindi `Company size` diventa `company_size`.

   Per scegliere tu la chiave, seleziona **Show advanced options** e modifica **Key**. Le chiavi vengono sempre salvate in questa forma minuscola con trattini bassi, e ogni chiave può esistere una sola volta per workspace.

3. **Scegli il tipo.** Scegli **Text**, **Number**, **Date**, **Boolean**, **Select** o **Multi select**.

4. **Aggiungi le opzioni per i campi di selezione.** Per **Select** e **Multi select**, inserisci almeno un’opzione e usa **Add option** per aggiungerne altre. Questi valori compaiono nel menu a tendina dei contatti.

5. **Salva.** Seleziona **Create**. Il campo compare su ogni contatto, nei filtri dei contatti e come tag di unione negli editor delle campagne.

La pagina Custom fields elenca tutti i campi con nome, tipo e opzioni. Usa **Edit** per rinominare un campo, cambiarne il tipo o la chiave, o modificarne le opzioni.

> **Eliminare un campo:** Eliminare un campo personalizzato lo rimuove dal pannello, dai filtri, dalle importazioni e dai tag di unione, e non si può annullare. Prima di cambiare o eliminare una chiave, aggiorna le campagne, le automazioni e il codice API che la usano.

## Imposta i valori

| Dove | Come |
| --- | --- |
| Pannello | **Add contact** o **Edit** su un contatto. Seleziona **Show custom fields** per vedere i campi. |
| Importazione | Associa una colonna del file al campo personalizzato nella procedura guidata di importazione. Vedi [Importa ed esporta i contatti](/it/docs/contacts/import-export/). |
| API | Invia un oggetto `custom_fields` indicizzato per chiave del campo. |

Con l’API, passa `custom_fields` a [Crea un contatto](/it/docs/api-reference/contacts/create/) o ad [Aggiorna un contatto](/it/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"]
    }
  }'
```

Regole da conoscere:

- **`custom_fields` sostituisce l’intero oggetto.** Nell’aggiornamento, includi tutti i valori che vuoi mantenere, non solo quelli che cambiano.
- **Usa le chiavi dei campi, non i nomi.** I valori per chiavi non definite in **Custom fields** vengono memorizzati, ma non compaiono nel pannello.
- **Le date devono essere nel formato `YYYY-MM-DD`.** Emailit converte in data le date-ora ISO e le celle data di Excel. Qualsiasi altro valore restituisce `400` con «Custom field "Birthday" must be a date in YYYY-MM-DD format». Le date non hanno ora né fuso orario.
- **I valori di selezione non vengono confrontati con le opzioni.** Un valore che non è nell’elenco delle opzioni viene comunque memorizzato, e il pannello continua a mostrarlo.

## Filtra i contatti per campo personalizzato

Nel pannello, apri **Email Marketing → Contacts**, seleziona **Filter** e scegli il campo personalizzato per nome. I filtri sui campi personalizzati confrontano il valore memorizzato come testo, quindi usa **equals**, **does not equal**, **contains**, **does not contain**, **starts with**, **ends with**, **is empty** o **is not empty**.

Con l’API, usa `custom_fields.<key>.<condition>` in [Elenca i contatti](/it/docs/api-reference/contacts/list/) ed [Esporta i contatti](/it/docs/api-reference/contacts/export/), con le stesse condizioni testuali (`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"
```

Per un intervallo, ad esempio i compleanni negli anni Novanta, usa i parametri `filter[custom_fields.<key>][gte]` e `[lte]`. Confrontano il testo memorizzato, che si ordina correttamente per le date `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"
```

Per sapere come si combinano i filtri, vedi [Filtri e ordinamento](/it/docs/api-reference/filtering/).

## Usa i campi personalizzati nelle campagne

Nei contenuti e negli oggetti delle campagne, inserisci un campo personalizzato con il tag di unione `{{cf.<key>}}`, ad esempio `{{cf.company}}`. Gli editor rich-text e Dragit elencano i campi personalizzati tra le loro variabili, quindi non devi scrivere la chiave.

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

Se un contatto non ha un valore, il tag viene sostituito con niente. I valori a selezione multipla vengono mostrati come elenco separato da virgole. Vedi [Tag di unione](/it/docs/campaigns/merge-tags/).

## Usa i campi personalizzati nelle automazioni

- **Trigger Date anniversary.** Scegli un campo **Date** per avviare un’esecuzione ogni anno nel mese e nel giorno memorizzati, ad esempio un compleanno. Vedi [Trigger](/it/docs/automations/triggers/#date-anniversary).
- **Trigger Contact updated.** Filtra su un campo personalizzato, o sul suo valore precedente, per reagire quando cambia.
- **Passaggio Condition.** Crea una diramazione in base al valore di un campo personalizzato.
- **Passaggio Edit contact.** Imposta un campo personalizzato inserendone la chiave.

## Riferimento API

Le definizioni dei campi personalizzati si gestiscono solo dal pannello. I valori dei contatti usano l’oggetto `custom_fields` dell’[API dei contatti](/it/docs/api-reference/contacts/), e lo stesso oggetto è accettato quando [aggiungi un iscritto](/it/docs/api-reference/audiences/subscribers/add/) a una lista.

## Vedi anche

  - [Contatti](/it/docs/contacts/): Come si combinano contatti, liste e iscritti.
  - [Tag di unione](/it/docs/campaigns/merge-tags/): Personalizza le campagne con i dati dei contatti.

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