Mautic custom fields: how to create and use them

The default fields in Mautic (name, email, phone, company, job title) cover the basics, but no business fits entirely inside them. Mautic custom fields store the data that is specific to your business on each contact (company size, product of interest, funnel stage, lead source), and that data is what you filter in segments, update from campaigns and drop into emails as tokens.

Before creating fields in bulk, it helps to see the cycle. A custom field starts with a data need, gets filled by some input (a form, an import, the API) and only pays off when you use it again in filters, automations and tokens.

What Mautic custom fields are

Mautic ships with a set of default contact fields: first name, last name, email, phone, company, job title, city, state, country and a few more. Every business has data those fields don't cover, and custom fields fill that gap. You create whatever your strategy needs: "Company Size", "Product of Interest", "Last Purchase Date", "Lead Source", "Order Number" and so on.

Each custom contact field becomes a real column in the contacts table of the database, so every field you add makes that table heavier. Create the ones you will actually filter on, fill in or use for personalization, and skip the ones created "just in case".

Where to create custom fields in Mautic

Open the admin panel through the gear icon in the top right corner and click Custom Fields in the side menu. The screen lists every existing field, including the default ones. To add one, click New and fill in the configuration screen.

Configuring a new custom field

Each option on the creation screen controls one aspect of how the field behaves.

Label and Alias

The Label is the friendly name shown in the interface (for example, "Company Size"). The Alias is the internal identifier, generated automatically from the label (for example, company_size). Tokens and integrations reference the alias, so avoid changing it after the field exists. Renaming the alias breaks every email token and integration that already points to it.

Object

This sets which entity the field belongs to: Contact (the person) or Company (the organization). A Contact field holds data about the individual and a Company field holds data about the business. Pick based on what the data describes, because the object can't be changed after creation.

Data type

The type decides how the value is stored and how the field behaves in forms and reports. Mautic custom fields come in many types. The table below covers the ones you'll use most.

Mautic also has Datetime, Time, Country, Region, Timezone and Locale for more specific cases. Always pick the type that matches the real data. A well-defined Select keeps the database consistent and stops the same value from being typed ten different ways.

Group

The Group setting controls where the field appears on the contact record. Mautic custom fields are split into groups such as Core, Social, Personal and Professional. Choose the group that fits the data so the contact profile stays readable and related fields sit together.

Default value

This is the value the field takes when no data comes in. It's handy for Boolean fields ("Subscribed to the newsletter" starts as "No") or for a Select where one option is far more common than the rest.

Required and visibility

If you tick Required, the field becomes mandatory on every form you add it to. Use it sparingly, since each required field adds friction for the person filling in the form. The Publicly Updatable option decides whether public actions, such as a form submission or tracking, can update the field. Keep it off for sensitive fields (an internal score, a lead rating) so nobody can overwrite them from outside.

Using custom fields in Mautic forms

Mautic custom fields become available as soon as you save them, including when you build forms under Components → Forms. When you add a field to a form, map it to the custom field through the element's Contact Field option. The value the lead types then goes straight into that field on the contact record, which is the most common way to feed a field from your website. For the full form walkthrough, see the guide to Mautic forms.

Using custom fields in segments

All your Mautic custom fields show up as filters when you build a segment (Contacts → Segments → Filters). That is what makes fine-grained segmentation possible, for example: "Company Size = Large AND Product of Interest = CRM AND points above 50". Dynamic segments are rebuilt by the segment cron job, so a contact enters and leaves the group as the field value changes. If the segment never updates, check your Mautic cron jobs first. Grouping strategy gets its own article in Mautic segments.

Personalization tokens in emails

Any custom field can go into a Mautic email as a token, using the {contactfield=alias} syntax. If the alias is company_size, the token is {contactfield=company_size}. To avoid a blank gap when the field is empty, use the version with a default value: {contactfield=company_size|your company}. Tokens like this make a bulk send read like a message written for one person.

FAQ about Mautic custom fields

What are custom fields in Mautic for?

They store business data that the default Mautic fields (name, email, phone, company, job title) don't cover, such as company size, product of interest, last purchase date or lead source. Once created, a field is available across the platform: forms can fill it, segments can filter by it, campaigns can update it and emails can insert it as a personalization token.

What is the difference between a Contact field and a Company field?

When you create the field, you pick the object it belongs to. A Contact field holds data about the person (job title, birthday, product of interest). A Company field holds data about the organization (revenue, industry, number of branches) and is available when a form or record collects company data. Choose based on the nature of the data, because the object can't be changed later.

Can I import data into custom fields from a CSV?

Yes. Under Contacts → Import you upload the CSV and map each column to a Mautic field, including the custom fields you created. Mautic matches records on the unique identifier field (email by default) and updates the existing contact instead of creating a duplicate.

How do I update a custom field automatically from a campaign?

Use the Update contact action inside a campaign. When the contact does something the flow expects (clicks a link, submits a form, reaches a point score), Mautic writes the new value to the field with no manual work. That is how you keep data like funnel stage, product of interest or lead source current.

How do I use a custom field in an email?

Every custom field becomes a personalization token in the format {contactfield=alias}, where "alias" is the field's internal identifier. If the alias is company_size, the token is {contactfield=company_size}. Tokens work in the subject line and the body. Use {contactfield=alias|value} to show a fallback text when the field is empty.

Planning your Mautic custom fields

Custom fields let you store, filter, automate and personalize on the data your marketing depends on, and like the rest of Mautic they come with no license cost.

Plan before you create fields in bulk. Each one should have a clear job in segmentation, forms, campaigns or personalization, and a few well-kept fields are worth more than dozens nobody fills in. If your scoring model depends on profile data like job title or company size, the Mautic lead scoring guide shows how to turn those fields into points. The reference for every option is in the official Mautic custom fields documentation.