Onboarding: Custom Fields

Each business has different data points that are relevant to its market. Mautic’s Custom Fields enable our customers to use those data points to personalize messaging, segment contacts, and run reports that can indicate which types of contacts are worth spending the most time and money targeting.

To get to the Custom Fields page in Mautic, click on the Settings icon in the top right corner and click on Custom Fields.

Custom Fields View

This page shows all existing contact fields, including standard fields and any custom contact fields you’ve created.

You will notice the group column which will show you where the specific field will be shown on the contact profile. In the last column, you may see several icons which signify various properties of the field:

  • Key: Fields with a key icon are the unique identifiers for the Contact or Company object
  • Lock: You can’t remove these fields as they are core to Mautic, though you can unpublish them so they don’t appear on contact records
  • List: You can use these fields as filters in Segments
  • Eye (with a slashmark): Fields with this icon are not available to use on contact forms
  • Asterisk: In order to save a new contact (manual add or CSV import), you must have data in these fields
  • Red globe: These fields are publicly updatable through the tracking pixel URL query

Published Fields

The clickable toggle which shows before each label title will publish (green) or unpublish (red) the field.

Creating New Custom Fields

You can create additional custom fields and define the data type you want that field to hold. In addition to the data type you will also select the group for that particular field. This defines where the field displays on the contact edit and detail view.

Custom Fields


Label: What you’ll see in the UI for each custom field

Alias: What Mautic uses to name the field on our database; you’ll use this Alias for API calls, tokens in emails, and other technical references to the Custom Field. Once you’ve saved the new Custom Field, you won’t be able to change this.

Object: You’re able to create fields for data relating to either the Contacts or Companies object. If the data you’re adding is more relevant for the accounts, companies, organizations, etc. that you’re working with, tie the field to the Companies object. If it’s data about an individual person, tie it to the Contacts object. Once you’ve saved the new Custom Field, you won’t be able to change this.

Group: On Contact or Company records, you’re able to group fields into Core, Social, Personal, and Professional tabs. This option on the Custom Field editor determines which tab the field appears in.

Data Type: This controls how Mautic validates the format of the data in the field. Once you’ve saved the new Custom Field, you won’t be able to change this.

Default Value: You can add a default value to populate the field with something rather than having a blank value. Once you’ve saved the new Custom Field, you won’t be able to change this.


Published: If a Custom Field is unpublished, you won’t see it anywhere else in the UI – contact records, segments, campaigns, reports, etc. It essentially doesn’t exist.

Required: Making a Custom Field required will prevent you from adding new contacts unless data exists in that field.

Visible on forms: Disabling this option will make the field unavailable for use on Mautic forms, so you won’t be able to map data to that field.

Visible on short forms: Fields with this option enabled will appear on the form in the modal when you use the Quick Add feature to manually add contacts in Mautic.

Available for segments: Exactly what you think it is. If you set this option to No, you won’t be able to use it as a Segment filter.

Publicly updatable: This is a technical feature, allowing you to update Custom Fields based on a tracking script event. If you’re tracking events behind the login of your SaaS platform or want to otherwise update a field based on some activity, you can use this option. There are other, less technical ways to achieve similar results as well.

Is unique identifier: Mautic uses email address as the default unique identifier for both the Contact and Company objects. However, it is possible to determine your own unique identifier or even have multiple unique IDs. Having multiple unique identifiers will likely result in having duplicate contacts.