> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings → Custom Fields console

> Use the /settings/custom-fields console to define typed contact fields, control their order in dashboard pickers, inspect tenant-owned usage, and retire fields safely.

# Settings → Custom Fields console

Open **Settings → Custom Fields** at `/settings/custom-fields` to manage the custom fields your organization uses on contacts and conversations. The console is the visual counterpart to the [Custom Fields API](/api-reference/custom-fields): use it when you want to review definitions, inspect usage, or retire a field without writing a request.

Custom-field definitions and their values are **tenant-owned controls**. Your organization's owner and admin roles can manage the definitions; every definition change is recorded in your tenant's [audit log](/guides/audit-log). This page describes the dashboard workflow. For API recipes and request/response shapes, see [Custom fields](/guides/custom-fields).

<Note>
  The console does not change a field's `key` or `type` after creation. If either property needs to change, create a replacement field, move its values and references, and then retire the old field.
</Note>

## What the console exposes

The page has three related surfaces: the definition list, the field editor, and the per-field tools. Start with the definition list to see how the tenant's fields are currently modeled.

### Definition list

Each row represents one definition and gives you the context needed before editing it:

* **Name and key** identify the label shown to operators and the stable key used in contact data, segments, flows, campaigns, and personalization.
* **Type** shows whether the value is `text`, `number`, `boolean`, `date`, `select`, `multiselect`, or `user_ref`.
* **Required** indicates whether contact writes must provide a value. Removing a required value is rejected.
* **Searchable** indicates whether the field is available to tenant search and filtering surfaces.
* **Validator summary** shows the constraints that apply to the type: length or numeric bounds, a regular expression, an allow-list, or select options.
* **Order** is the position used by dashboard pickers. Unordered fields appear after explicitly ordered fields.

Select a row to open its definition details. You can edit the display name, description, options, default, required/searchable flags, and validators. The `key` and `type` remain read-only because existing contact values and references depend on them.

### Per-type validators

The editor only enables validators that make sense for the selected type. Use the validator summary as a quick check before saving:

| Type | Validators the console can apply | What to check before saving |
| - | - | - |
| `text` | Regex, character minimum/maximum, exact allow-list | The complete string must match the regex and stay within the length limits. |
| `number` | Numeric minimum/maximum | Bounds are numeric, not character counts. |
| `boolean` | Type validation | Values must resolve to `true` or `false`; do not use an arbitrary label for a boolean flag. |
| `date` | Date validation | Use an ISO 8601 date or datetime for values used in date filters. |
| `select` | Options, with optional exact allow-list | Every value must be one of the configured options. Regex and length validators do not constrain select membership. |
| `multiselect` | Options, per-entry validation, selection minimum/maximum | The length limits count selections, and every entry must be allowed. |
| `user_ref` | Regex, character minimum/maximum, exact allow-list | Store the teammate's user id, not a display name. |

The console validates an edited default against the same rules as a contact value. A failed validator leaves the definition unchanged; correct the value or validator and save again.

## Reorder fields for dashboard pickers

The order in the definition list controls the order operators see when they choose a custom field in dashboard surfaces such as contact filters, segment conditions, and other field pickers. It does not rename a field, change its key, or alter the order of values already stored on contacts.

1. Open **Settings → Custom Fields**.
2. Drag a field by its reorder handle, or use the row's move controls to place it above or below another field.
3. Arrange the fields from the most frequently used to the least frequently used. Put fields that operators use together next to each other.
4. Save the new order.
5. Open a dashboard field picker and confirm that the definitions appear in the same top-to-bottom order.

The saved order is tenant-scoped. It applies to the organization's dashboard pickers, not to another tenant's definitions. If a field has no explicit position, it appears after the ordered fields; use the console to place it deliberately when picker order matters.

Reordering is presentation-only. It does not affect segment evaluation, flow execution, campaign enrollment, contact values, or API key names.

## Use the explorer panel before changing a definition

Open a field's row and choose **Explorer** to inspect how the field is used in your tenant without leaving the dashboard. The explorer panel combines the definition with a read-only usage snapshot:

* **Contact usage count** shows how many contacts currently carry a value for the field.
* **Segment, campaign, and flow counts** show how many tenant automations and audiences reference it.
* **Recent samples** show up to ten distinct recently written values so you can spot unexpected formats before tightening a validator or changing options.

Samples are PII-redacted and truncated in the panel. Treat them as a shape check, not as a way to recover a contact's original value. If a sample looks sensitive or unexpected, use your tenant's normal data-governance process rather than copying it into a ticket or an external document.

Use the explorer when you are about to:

* Narrow a `select` or `multiselect` option list.
* Tighten a regex or a length bound.
* Change a default value.
* Decide whether a replacement field has enough coverage to take over from an older field.

The explorer is a dashboard read surface; you do not need curl or an API key to use it. For the API equivalent and response shape, see the [field explorer section in the API guide](/guides/custom-fields#the-explorer).

## Run a dependency scan before retiring a field

A field can be referenced by more than the contacts that store it. Open the field's tools and choose **Dependency scan** before deleting or repurposing the definition. The panel lists the tenant-owned surfaces that would be affected:

* **Segments** whose filters use the field.
* **Campaigns** whose audience rules, variables, or metadata reference the field.
* **Flows**, including automation and IVR flows, whose conditions reference the field.
* **Contacts with data**, the number of contact records that currently carry a value.
* **Drip enrollments**, when campaign references have active or paused enrollments.

Open each result to identify the segment, campaign, or flow rather than relying only on the totals. Remove or replace the references first when the surface is live. For a migration, create the replacement field, backfill values, repoint the listed dependents, and run the scan again until the old field has no references you still need.

A scan is a point-in-time view. Run it again immediately before the final delete if another operator may have edited a segment, campaign, or flow since your first review. The scan also makes the retirement decision auditable alongside the definition change.

## Retire flows and confirm a forced delete

Use the normal delete action only after reviewing the dependency scan. If the field has no dependents, the console can delete it directly after the standard confirmation.

When references remain, the console blocks a normal delete and opens the **forced-delete confirmation dialog**. The dialog lists the affected segments, campaigns, flows, and contacts, and explains what will happen if you continue. Do not confirm until you have decided which dependents to rebuild.

To retire a referenced field safely:

1. Open **Explorer** and note the usage counts and sample shapes.
2. Open **Dependency scan** and review every named segment, campaign, flow, and contact count.
3. Remove the old field from live filters and flow conditions, or create replacement definitions and repoint those surfaces.
4. Return to the field row and choose **Delete**.
5. If the forced-delete dialog appears, review the dependent list again and type the requested confirmation. Choose **Cancel** if any live reference still needs cleanup; choose **Force delete** only when you accept the listed impact.
6. Open the affected surfaces after deletion and repair any items marked as broken.

A forced delete is deliberately visible rather than silent:

* Segments that referenced the field are marked broken until you edit their filters.
* Automation and IVR flows that referenced it are marked broken and do not run with an orphaned condition.
* Campaigns finish an in-flight send but carry a broken-custom-field marker so you can find and repair them.
* Contacts lose the retired key and its stored values as part of the same operation.

The dialog is a safeguard, not a migration tool. If you need to preserve the data, backfill a replacement field and repoint dependents before confirming. Review the [custom-field lifecycle](/guides/custom-fields#lifecycle-rules-whats-locked-and-how-to-migrate) for the API-assisted migration sequence.

## Troubleshoot common console outcomes

* **A save is rejected:** check the selected type, default value, options, and validator bounds. The `key` and `type` cannot be edited in place.
* **A picker does not show the new order:** save the reorder, refresh the dashboard surface, and confirm that the fields have explicit positions. Unordered fields trail ordered fields.
* **Explorer counts look stale:** run the explorer again after the underlying contact, segment, campaign, or flow change has finished saving. The panel is a snapshot, not a live stream.
* **Delete is blocked:** open the dependency scan and resolve the listed references, or use the forced-delete dialog only after accepting the displayed impact.

## See also

* [Custom fields](/guides/custom-fields) — API recipes, type details, validators, limits, and migration rules.
* [Custom Fields API reference](/api-reference/custom-fields) — endpoint request and response shapes.
* [Segments](/api-reference/segments) — build audience filters with custom fields.
* [Audit log](/guides/audit-log) — review tenant-scoped configuration changes.
* [Settings hub](/settings/overview) — find the Custom Fields console with the other organization settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.