Overview

In Zylo, customizable fields can be created for applications, contracts, and payments. These fields (referred to commonly as "Custom Fields") allow for users to create their own updateable and filterable fields that are attached to an application, contract, or payment.

Creating a payments- or contracts-scoped custom field requires the corresponding custom fields feature to be enabled for your company; see Choosing the entity_type below. Applications-scoped custom fields are unaffected.

Below is a table describing how each type of custom field:

Note on the options Property

When retrieving a Custom Field from either the List or the By ID routes the individual record's options will have varying shapes:

If boolean type

{
  ...
  "type": "boolean",
  "options": {
    "default": "Yes",
    "options": [
      "Yes",
      "No",
      "Not Specified (-)"
    ]
  },
  ...
}

If choice type

{
  ...
  "type": "choice",
  "options": {
    "default": "value1",
    "options": [
      "value1",
      "value2",
      "value3"
    ],
    "disabled_options": []
  },
  ...
}

For all other types; currency, date, email, number, and text

{
  ...
  "type": "text",
  "options": {},
  ...
}

Creating a Custom field

Choosing the entity_type

The entity_type property controls which resource the custom field applies to. It accepts applications, contracts, or payments, and defaults to applications when omitted.

{
  ...
  "entity_type": "applications", // or "contracts" / "payments" (feature-gated — see below)
  ...
}

entity_type is set at creation only and cannot be changed afterward — a field's scope is fixed for the life of the field.

Creating a payments- or contracts-scoped custom field requires the corresponding custom fields feature to be enabled for your company. When the feature is not enabled, a request with that entity_type is rejected; applications-scoped fields are unaffected.

Choosing the boolean type

When creating a boolean type the options top level property must take the shape:

{
  ...
  "type": "boolean",
  "options": {
    "default": "Yes", // or "No" or "Not Specified (-)"
    "options": [
      "Yes",
      "No",
      "Not Specified (-)"
    ]
  },
  ...
}

The options array must contain the values Yes, No, Not Specified (-), or a subset of those three.

The default may be omitted, null, or empty string ''. However if one of those values are pass the default will be set to Not Specified (-).

Choosing the choice type

When creating a choice type the options top level property must take the shape:

{
  ...
  "type": "choice",
  "options": {
    "default": "value1", // or "value2" or "value3"
    "options": [
      "value1",
      "value2",
      "value3"
    ]
  },
  ...
}

The default may be omitted, null, or empty string ''. However if any other value then it must be present in the options array.

NOTE: the disabled_options array cannot be modified through the API.

Choosing currency, date, email, number, and text types

When choosing one of these types the options property can be omitted, null, or an empty object {}.

Updating a Custom field

Currently only the description, is_enabled, and position are the only properties that can be updated at this time. In particular, entity_type cannot be changed after a field is created.