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) 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.

​
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.
  • 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.

​
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.