Skip to main content
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

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

1

Open the dialog

Click Add Field.
2

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) and Multi-select 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.
3

Save

Click Create Field. The field appears in the table with its name, key, type and whether it is required.
Choose the key and type carefully: they can’t be changed later. Merge tags and API integrations refer to the field by its key.

Sensitive fields

Tick Sensitive — keep out of AI when you create or edit a field that holds something you never want an AI model to see, such as a health note or an internal score. A sensitive field works like any other in emails, merge tags, segments and the API, but Spark and connected MCP assistants see only its key and type: its options and description are withheld, and a segment or automation rule that uses it shows its value as [sensitive]. A sensitive field is also left out of the synthetic panel, which otherwise describes dropdown and yes/no fields as option shares. Sensitive fields carry a Sensitive badge in the table. See AI data privacy.

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 or multi-select field doesn’t change contacts that already have that value.

Multi-select fields

A Multi-select field holds several of its options at once — one interests field with running, yoga and swimming instead of a yes/no field per topic. A contact can have none, one or all of them, and only the options you declared can be stored. In an automation, the Update contact step adds the options you tick to whatever the contact already holds, so interests collected by different automations accumulate. Switch How to apply to Replace to overwrite them, or Remove to take the ticked options away.
  • On the contact page and in the Add Contact dialog it is a group of checkboxes.
  • On signup forms it is a checkbox group, and a quiz answer mapped to it adds its option, never removing the others.
  • In the API send an array, such as "customFields": { "interests": ["running", "yoga"] }; reads return an array too. A string like running; yoga also works.
  • In a CSV import a cell can be running;yoga, running, yoga or ["running","yoga"]; values are matched to the declared options regardless of capitals, and anything that isn’t an option is skipped. Exports write running; yoga.
  • In segments use is any of, is all of, is none of, is empty and is not empty. See Segments.

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.
  • CSV import: map a column to the field in the import dialog’s Maps To list. See Import contacts.

Use custom fields

In segments. Every custom field appears in the segment builder as Name (custom), with operators that suit its type. See Segments. 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:
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. A multi-select field prints its options separated by commas (running, yoga). In Liquid you can also loop over them:

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

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.
A custom field marked Required field has no value. Fill it in, or edit the field and clear Required field.