Reference: Client fields JSON (`custom_fields_json`)

This page lists properties of a single field object in Client Fields (/settings-page/client-fields). The saved configuration includes a wrapper with the key custom_fields_json; inside it, each key is the field’s technical name (Latin), and the value is the field definition.

Step-by-step: How to configure client fields. Visibility can be changed there (one header Save) or on the op-settings page — same block, different save affordance.

Saved data shape

After saving to instance settings, the payload uses client_fields_json, which contains custom_fields_json:

{
  "custom_fields_json": {
    "department": {
      "type": "STRING",
      "label": "Department"
    }
  }
}

Values that operators enter in the client card are stored in the client’s extra_data under these field keys.

Core field properties

Property	Required	Description
`type`	Effectively required	Data type. See the table below.
`label`	Recommended	Label shown in the UI (client card, tables).

Allowed `type` values

Value	Purpose
`STRING`	Short text
`TEXT`	Multiline text
`SELECT`	Fixed list selection
`SELECTAPI`	Selection from an API-backed source
`FILE`	File
`INTEGER`	Integer
`BIGINT`	Large integer
`FLOAT`	Decimal number
`DATE`	Date
`BOOLEAN`	Yes / no

Additional properties (form and JSON)

On the Client Fields page, many options can be set in the field card (form sections); everything can also be edited in raw JSON. In the saved JSON, most toggles are stored as the string "true"; when off, the key is usually omitted.

General and editing

Key	JSON type	What it does
`default`	string	Default value on create / fallback (depending on UI behavior).
`unique`	`"true"`	Disallow duplicate values for this field (enforcement depends on usage).
`non_editable`	`"true"`	Read-only for operators in the UI.

Table display

Key	JSON type	What it does
`sortable`	`"true"`	Enable sorting by this column in the clients table.
`width`	string	Column width in pixels, e.g. `"120"`.
`align`	`""` / `"start"` / `"center"` / `"end"`	Header alignment. Empty means default.
`display_in_table`	`""` / `"image"`	Cell rendering mode; `image` shows an image where data allows.
`display_type`	`"link"`	For string-like fields: value is treated as a link opening in a new tab.
`click_action`	`"open"`	For string-like fields: click opens an edit modal. Do not combine with `display_type: "link"` — the form’s “action on click” control is mutually exclusive.

Visibility

Key	JSON type	What it does
`hidden_all`	`"true"`	Hide the field everywhere in the card and related forms (same as the UI toggle).
`hidden_in_table`	`"true"`	Hide the column from the table column picker.
`hide_in_filter`	`"true"`	Hide the field from filters.
`hidden_in_create_popup`	`"true"` or `true`	Hide in quick-create popup when that flow is used.
`portal_registration`	`"true"` or `true`	Show on Client Portal self-registration form (`/register`). Values stored in `OpClients.extra_data`. In Constructor UI: toggle Show on Client Portal registration on `/settings-page/client-fields`. Does not control operator client card visibility.

Client Portal (registration)

Works together with instance settings portal_registration_enabled and portal_registration_role_id. Types SELECTAPI and FILE are excluded from the registration form even when the flag is set. See Configure instance settings and Configure roles.

Validation: `rules`

An array of rule name strings. Values available from the picker:

Value	Purpose
`required`	Required value
`email`	Email format
`digits`	Digits only
`latin`	Latin characters only
`latinDigits`	Latin letters and digits
`stringMaxLength`	Max length (may need extra parameters in JSON for advanced cases)
`json`	JSON format check

Complex cross-field rules may use a separate validate object. Use the JSON examples on the settings page or keep a backup before editing.

Example:

"email_field": {
  "type": "STRING",
  "label": "Email",
  "rules": ["required", "email"]
}

JSON examples block

The JSON examples section at the bottom of the editor lists five snippets with the same JSON as in How to configure client fields (JSON examples). The documentation adds a short narrative for each scenario; the product UI only shows short selector labels.

Limits and tips

Invalid JSON will not save: check commas, quotes, and brackets.
Back up the configuration before large edits.
Removing a field here does not automatically remove its key from the card visibility settings; update the field editor in the client card if needed.

Reference: Client fields JSON (custom_fields_json)