Create a custom field

The fastest path from “we should track this” to a usable field. Fields are available immediately after creation — no deploy, no restart, no migration.

Before you start

• Admin permissions on Custom Fields
• A clear answer to two questions:
  Which entity does this field belong to — contact, conversation, or case?
  What field type fits the data?

If you’re unsure on the type, take 30 seconds to read the field types reference. Switching types later usually means recreating the field and losing the data already in it.

Steps

1. Open Settings → Custom Fields.
2. Pick the entity at the top of the page: Contacts, Conversations, or Cases.
3. Click New field.
4. Fill in the field properties:
   Name — the label agents see (e.g. Order Number, Contract Tier). Use Title Case and be specific — External Order Number is clearer than Order.
   Key — auto-generated from the name, used as the machine identifier in automations and API calls. You can override it if you need a stable key (e.g. order_id instead of external_order_number).
   Type — pick from Text, Textarea, Number, Date, Select, or Checkbox.
   Required — leave off unless agents must fill it in for every record. Required fields block save until they’re populated.
   Section — optional grouping. If you don’t pick one, the field appears in the default group.
   Display order — where the field appears relative to siblings.
5. For Select fields only: add the list of options. Each option needs a label (what agents see) and gets an auto-generated value (the machine slug used in conditions and analytics).
6. Click Save.

The field is now available on every contact, conversation, or case in the chosen area.

Verify it worked

1. Open a record in the chosen area (a contact, a conversation, or a case).
2. Look for the new field — by default it appears in the right-hand panel or in its assigned section.
3. Set a value, save, reload. The value should persist.

Pick the field’s home wisely

The same data point can technically live on more than one entity, but pick one:

• Order number — usually a conversation field. The customer is contacting you about a specific order; the order changes from conversation to conversation.
• Contract tier — usually a contact field. It’s an attribute of the customer, not the conversation.
• Affected system — usually a case field if you use Cases; otherwise a conversation field.

Putting the same field on two entities causes drift — the contact-level value disagrees with the conversation-level value, and nobody knows which is “right.”

Troubleshooting

• Symptom: Field appears in Settings but doesn’t show up on conversations. Fix: Confirm you picked the right entity tab when creating it. A field created under Contacts won’t appear on conversations and vice versa.
• Symptom: Required field blocks me from saving a conversation that already existed before the field was created. Fix: Required fields apply to new and edited records. Pre-existing records aren’t backfilled. If you want to enforce population, run a manual sweep or use an automation that flags records missing the field.
• Symptom: Select field option labels show up wrong in conditions. Fix: Conditions compare against the option’s value (machine slug), not the label. Look up the slug in Settings → Custom Fields → the field → Options.

See also

• Field types reference
• Organize with sections
• Use a custom field in an automation