> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instantcampaign.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom fields

> Store your own data on contacts, such as plan tier or purchase count, and use it in segments and emails.

Contacts come with built-in fields: email, name, company, job title, phone, address, country, language, timezone and birthday. **Custom fields** add your own, for example `plan_tier`, `purchase_count` or `renewal_date`.

Open **Settings → Custom Fields**. The page lives at `/contacts/fields`.

## Field types

| Type                  | Stores                                                     | Entered as                             |
| --------------------- | ---------------------------------------------------------- | -------------------------------------- |
| **Text**              | Any text                                                   | Text box                               |
| **Number**            | A number                                                   | Number box                             |
| **Boolean**           | Yes / no                                                   | Checkbox                               |
| **Date**              | A calendar date                                            | Date picker                            |
| **Select (dropdown)** | One value from a fixed set of options                      | Dropdown                               |
| **JSON**              | Structured data, such as `{"size": "M", "colour": "blue"}` | Text box; the value must be valid JSON |

A JSON value is stored as its text: segment rules match it with the text operators (such as **contains**), and a merge tag prints the JSON text.

## Create a field

<Steps>
  <Step title="Open the dialog">
    Click **Add Field**.
  </Step>

  <Step title="Describe the field">
    * **Field Name**: the label people see, such as "Plan Tier".
    * **Key**: the machine-readable name used in merge tags, the API and exports. Lowercase letters, numbers and underscores only, such as `plan_tier`.
    * **Type**: one of the types above.
    * **Options (comma-separated)**: for **Select (dropdown)** fields only, for example `free, pro, enterprise`. At least one option is required.
    * **Description**: optional note on what the field is for.
    * **Required field**: marks the field as required in the **Add Contact** form.
  </Step>

  <Step title="Save">
    Click **Create Field**. The field appears in the table with its name, key, type and whether it is required.
  </Step>
</Steps>

<Warning>
  Choose the key and type carefully: they can't be changed later. Merge tags and API integrations refer to the field by its key.
</Warning>

## Edit a field

Click the pencil icon in the field's row. You can change the **Field Name**, **Description**, **Options** (for dropdowns) and **Required field**. The key and type are shown but can't be changed. Stored values are kept. Adding, editing and deleting fields needs permission to edit contacts (Owner, Administrator and Data manager have it).

Removing an option from a dropdown doesn't change contacts that already have that value.

## Set values

* **One contact**: on the contact page, click **Edit Contact**. New contacts can be given values in the **Add Contact** dialog.
* **Many contacts**: select them in the contacts table and use **Bulk update → Set a custom field**.
* **API**: send custom field values with the contact. See the [API reference](/api-reference/introduction).
* **CSV import**: map a column to the field in the import dialog's **Maps To** list. See [Import contacts](/guides/audience-and-campaigns/import-contacts#custom-fields).

## Use custom fields

**In segments.** Every custom field appears in the segment builder as **Name (custom)**, with operators that suit its type. See [Segments](/guides/audience-and-campaigns/segments#custom-field-operators).

**In the contacts table.** Turn on the **Custom Fields** column in the column chooser. Custom fields are also exported as columns in the contacts CSV.

**In emails.** Insert a value with its key:

```liquid theme={null}
Your plan: {{customField:plan_tier}}
Your plan: {{customField:plan_tier | Free}}
```

The second form prints `Free` when the contact has no value. In templates that use Liquid, use `{{ customField.plan_tier }}`, which works in campaigns, journeys and transactional email. Journeys and transactional email also accept `{{ contact.plan_tier }}`; campaigns do not, so prefer `customField.*`.

A custom field with no value renders as empty text (or the fallback) rather than as the raw tag.

## Delete a field

Click the trash icon in the field's row and confirm. Deleting a field removes every stored value for it, on every contact. Segments, templates and integrations that use it will no longer find a value.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A merge tag prints nothing">
    Check the key, not the display name: `{{customField:plan_tier}}`, not `{{customField:Plan Tier}}`. Then check that the contact actually has a value on its page.
  </Accordion>

  <Accordion title="I can't save the Add Contact form">
    A custom field marked **Required field** has no value. Fill it in, or [edit the field](#edit-a-field) and clear **Required field**.
  </Accordion>
</AccordionGroup>