Skip to main content

​
Custom Fields

Orbit’s contact record covers what every business needs (name, phone, email, channel preferences). The moment you need something specific to your business — plan_tier, lifetime_value, account_manager, renewal_date — you define a custom field instead of stuffing it into a note or an external spreadsheet. Once defined, the field behaves like a first-class contact attribute: it shows up on the contact record, it’s filterable in segments, it’s usable as a condition in flows, and it can be dropped into a message with {{custom.plan_tier}}-style personalization. This guide covers when to reach for a custom field, how the types and validators work, and how to retire one safely. For the full request/response schemas, see the Custom Fields API reference.

​
When to use a custom field

Reach for a custom field when a piece of contact data needs to be:
  • Structured — typed and validated, not a freeform note.
  • Queryable — you want to build a segment like “plan_tier = enterprise AND lifetime_value > 5000”.
  • Reusable — the same value drives a flow condition, a campaign filter, and a personalization token, and you don’t want three separate places to keep it in sync.
If you only need to leave a one-off comment on a contact, use the contact’s notes instead — a custom field is for data your workflows act on.

​
Field types

select and multiselect require an options array at creation time. A field’s key and type are locked in at creation — you can’t change either with a later update, because doing so would orphan the values already stored on contacts. If you need a different type, create a new field and migrate the data.

​
Creating a field and setting values

Field values you set are read back inline on the contact resource alongside the built-in attributes — there’s no separate “fetch custom fields” call in the read path.

​
Validation

Beyond the type system, a field can carry optional validators applied whenever a value is written:
  • validator_regex — a regex enforced on string-shaped values.
  • min_len / max_len — character length for text, numeric range for number, entry count for multiselect.
  • enum_values — an exact allow-list layered on top of the type (only for text, select, multiselect, user_ref — a number/date/boolean field uses the range or the type itself instead).
A value that fails validation is rejected with 422 VALIDATION_ERROR at write time, so bad data never reaches a contact.

​
Retiring a field safely

Before you delete a field, check what depends on it:
This returns the segments, campaigns, and flows referencing the field, plus how many contacts carry a value for it. DELETE is guarded: if anything depends on the field, the request fails with 409 CUSTOM_FIELD_IN_USE instead of silently breaking a live segment or automation. To delete anyway, pass ?force=true — dependent segments and flows are marked broken so they stop matching or running, and dependent campaigns keep any send in flight but are flagged so you can find and fix them. The field’s values are stripped from every contact either way. Use the field explorer (GET /custom-fields/{id}/explorer) to see usage counts and a sample of stored values (PII-redacted) before you decide whether to retire a field or just update its options.

​
See also