# Custom fields

> Define custom fields for your contacts, set their values from the dashboard, imports and the API, and use them in filters, campaign merge tags and automations.

Custom fields store extra data on each contact, such as a company name, a plan or a birthday. You define the fields once for the workspace, then fill them in on contacts and use them to filter contacts, personalize campaigns and start automations.

## Field types

| Type | Stored value | Example | Dashboard input |
| --- | --- | --- | --- |
| **Text** | String | `"Acme"` | Text box |
| **Number** | Number | `42` | Number box |
| **Date** | Calendar date, `YYYY-MM-DD` | `"1990-04-12"` | Date picker |
| **Boolean** | `true` or `false` | `true` | Checkbox |
| **Select** | One option | `"pro"` | Dropdown |
| **Multi select** | Array of options | `["news", "offers"]` | Multi-select dropdown |

Each field has a **name**, which the dashboard shows, and a **key**, which the API, imports, filters and merge tags use. Values are stored on the contact as a JSON object keyed by field key:

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

## Create a custom field

1. **Open Custom fields.** Go to **Workspace → Settings → Custom fields** and select **Add custom field**.

2. **Name the field.** Enter a **Name**, for example `Company size`. Emailit builds the key from the name automatically: lowercase, with every run of other characters replaced by `_`, so `Company size` becomes `company_size`.

   To choose the key yourself, select **Show advanced options** and edit **Key**. Keys are always saved in that lowercase, underscore form, and each key can exist only once per workspace.

3. **Pick the type.** Choose **Text**, **Number**, **Date**, **Boolean**, **Select** or **Multi select**.

4. **Add options for select fields.** For **Select** and **Multi select**, enter at least one option and use **Add option** for more. These values appear in the dropdown on contacts.

5. **Save.** Select **Create**. The field appears on every contact, in the contact filters and as a merge tag in the campaign editors.

The Custom fields page lists every field with its name, type and options. Use **Edit** to rename a field, change its type or key, or edit its options.

> **Deleting a field:** Deleting a custom field removes it from the dashboard, filters, imports and merge tags, and you can't undo it. Before you change or delete a key, update any campaigns, automations and API code that use it.

## Set values

| Where | How |
| --- | --- |
| Dashboard | **Add contact** or **Edit** on a contact. Select **Show custom fields** to see the inputs. |
| Import | Map a file column to the custom field in the import wizard. See [Import and export contacts](/docs/contacts/import-export/). |
| API | Send a `custom_fields` object keyed by field key. |

With the API, pass `custom_fields` to [Create a contact](/docs/api-reference/contacts/create/) or [Update a contact](/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"]
    }
  }'
```

Rules to know:

- **`custom_fields` replaces the whole object.** On update, include every value you want to keep, not only the ones that change.
- **Use field keys, not names.** Values for keys that aren't defined in **Custom fields** are stored but don't show in the dashboard.
- **Dates must be `YYYY-MM-DD`.** Emailit converts ISO date-times and Excel date cells to a date. Anything else returns `400` with "Custom field "Birthday" must be a date in YYYY-MM-DD format". Dates have no time or time zone.
- **Select values aren't checked against the options.** A value that isn't in the option list is still stored, and the dashboard keeps showing it.

## Filter contacts by a custom field

In the dashboard, open **Email Marketing → Contacts**, select **Filter** and pick the custom field by its name. Custom field filters compare the stored value as text, so use **equals**, **does not equal**, **contains**, **does not contain**, **starts with**, **ends with**, **is empty** or **is not empty**.

With the API, use `custom_fields.<key>.<condition>` on [List contacts](/docs/api-reference/contacts/list/) and [Export contacts](/docs/api-reference/contacts/export/), with the same text conditions (`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"
```

For a range, such as birthdays in the 1990s, use the `filter[custom_fields.<key>][gte]` and `[lte]` parameters. They compare the stored text, which sorts correctly for `YYYY-MM-DD` dates:

```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"
```

See [Filtering](/docs/api-reference/filtering/) for how filters combine.

## Use custom fields in campaigns

In campaign content and subjects, insert a custom field with the merge tag `{{cf.<key>}}`, for example `{{cf.company}}`. The rich-text and Dragit editors list your custom fields under their variables, so you don't have to type the key.

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

If a contact has no value, the tag is replaced with nothing. Multi select values render as a comma-separated list. See [Merge tags](/docs/campaigns/merge-tags/).

## Use custom fields in automations

- **Date anniversary trigger.** Pick a **Date** field to start a run every year on the month and day stored in it, for example a birthday. See [Triggers](/docs/automations/triggers/#date-anniversary).
- **Contact updated trigger.** Filter on a custom field, or on its previous value, to react when it changes.
- **Condition step.** Branch on a custom field value.
- **Edit contact step.** Set a custom field by entering its key.

## API reference

Custom field definitions are managed in the dashboard only. Contact values use the `custom_fields` object on the [Contacts API](/docs/api-reference/contacts/), and the same object is accepted when you [add a subscriber](/docs/api-reference/audiences/subscribers/add/) to an audience.

## Related

  - [Contacts](/docs/contacts/): How contacts, audiences and subscribers fit together.
  - [Merge tags](/docs/campaigns/merge-tags/): Personalize campaigns with contact data.

---
Source: https://emailit.com/docs/contacts/custom-fields/