Custom field attributes

The custom field endpoints administer the definitions of custom fields: name, type, choices, display settings. To read or set the values of custom fields on a call, use the call object and Set custom field values.

Custom fields are configured in the web portal under Administration › Customization › Custom Fields. See Custom fields.

Example of a custom field object:

{
    "custom_field": {
        "field_id": "9079d60a-5192-11ee-aa89-0015172d2a7d",
        "tenant_id": null,
        "is_global": true,
        "name": "Call type",
        "computer_name": "call_type",
        "description": "Type of the call, like Sales, Collection, etc.",
        "type": "option",
        "enable": true,
        "editable": true,
        "dashboard": false,
        "fieldset_dropdown_value_settings": {
            "use_tenant_options": false,
            "options": [
                {"value": "Sales call", "color": "#00AA00"},
                {"value": "Collection call", "color": ""}
            ]
        },
        "fieldset_display_settings": {
            "display_group": null,
            "display_order": null,
            "display_prefix": null,
            "display_suffix": null,
            "show_in_compact_view": false
        }
    }
}

Attributes

Attribute	Type	Description
`field_id`	UUID	Unique ID of the custom field, assigned by MiaRec when the field is created. Read-only.
`tenant_id`	UUID or null	ID of the tenant the field belongs to. Returned only to API users of the System tenant in multi-tenant deployments. `null` for a global field. A tenant user creates fields in their own tenant.
`is_global`	boolean	Make the field visible to all tenants. Only an API user of the System tenant with the Unrestricted or System access scope can create global fields. Default `false`.
name	string	Name of the field, shown to users. Required. 1 to 64 characters.
`computer_name`	string or null	API name: a stable identifier for integrations. Unique within the tenant.
description	string or null	Description of the field, up to 4096 characters.
type	string	Type of the field: string - free text (default) integer - a number date - a date option - one of a fixed list of choices (drop-down)
enable	boolean	When `false`, the field is hidden: users cannot view, search, or edit its values. Stored values are kept. Default `false`.
editable	boolean	Allow authorized users to edit the values of this field in the web portal and through the REST API. Users need the Edit action of the Call custom fields permission. Default `false`.
dashboard	boolean	Show a dashboard for this field (number fields). Default `false`.
`fieldset_text_value_settings`	dictionary	Settings of a `string` field. See Text value settings.
`fieldset_integer_value_settings`	dictionary	Settings of an `integer` field. See Integer value settings.
`fieldset_dropdown_value_settings`	dictionary	Settings of an `option` field. See Dropdown value settings.
`fieldset_display_settings`	dictionary	Display settings. See Display settings.

Only the fieldset that matches the type is returned.

Text value settings

Attribute	Type	Description
`str_max_len`	integer	Maximum length of the value, from 1 to 1048576 characters. Default 1024.
`display_as`	string	Display widget: `default`, `label`, or `multiline` (for long texts such as a call summary). Default `default`.

Integer value settings

Attribute	Type	Description
`int_min`	integer	Minimum value. Default 0.
`int_max`	integer	Maximum value. Default 10.
`display_decimals`	integer or null	Number of decimals to display, 0 to 6.
`display_multiplier`	number or null	Multiply the value by this factor before display, 0.001 to 1000000.
aggregate	string	Aggregate formula for dashboards and reports: `avg`, `sum`, `top_percentage`, `bottom_percentage`, or `top_bottom_diff`.
`fieldset_thresholds`	dictionary	`{"thresholds": [...]}`. Value buckets that group values into labeled bands on dashboards. Each threshold has `op` (`lt`, `le`, `gt`, `ge`, `eq`, `ne`), `value` (integer), `label` (string), and `color` (string).

Attribute	Type	Description
options	list	Choices. Each choice has `value` (string, up to 256 characters) and `color` (string, hex color or empty).
`use_tenant_options`	boolean	For a global field: let each tenant define its own choices instead of the system-provided ones.

Display settings

Attribute	Type	Description
`display_group`	string or null	Group in which the field is shown on the conversation detail page.
`display_order`	integer or null	Order of the field within its group.
`display_prefix`	string or null	Text shown before the value, for example a currency symbol.
`display_suffix`	string or null	Text shown after the value.
`show_in_compact_view`	boolean	Show the field in the compact call details view. Default `false`.

Legacy attributes

Earlier versions of the API accepted these settings as top-level attributes of custom_field: str_max_len, display_as, options (a plain list of strings), use_tenant_options, int_min, int_max, display_decimals, display_multiplier, aggregate, thresholds, display_group, display_order, display_prefix, display_suffix, and show_in_compact_view, and the fieldsets fieldset_options and fieldset_thresholds. They are still accepted in requests and moved to the fieldsets above, but they are not returned in responses. Update your integration to the fieldset structure. The ai_assist and search_options attributes are ignored.