Using custom fields

Custom fields are fields you may create for several entities that allow you to capture additional relevant information and they are grouped together in custom field sets.

A custom field consists of the custom field definition and the custom field value. The custom field definition is the custom field you create using either the Mambu UI or API which contains information such as its name, ID, type, and usage settings. The custom field value is the actual value that a custom field attached to an entity holds. For more information about custom fields, how to create them, and which entities support them, see Custom Fields in our User Guide.

In API v2, if a JSON object includes a custom field value, then at the end of the JSON object, there will be a custom field set property which will contain the custom field definition ID and the custom field value.

note

A custom field value in a request body may not be an empty string or null regardless of whether the custom field definition is marked as required or not.

There are two kinds of custom field sets, standard and grouped.

A standard custom field set can contain multiple single custom field definitions. Each custom field definition may contain only one value. In a JSON object, it is represented by a custom field set property that contains an object with the associated custom field values.

A grouped custom field set contains groups of custom field definitions. You may have multiple groups of custom field definitions within the custom field set. In a JSON object, it is represented by a custom field set property that contains an array of objects with the associated custom field values and the index of each object in the array.

The type of custom field set dictates how custom field definitions and their values must be handled in PATCH operations.

Here is an example of a single custom field set and a grouped custom field set:

Single custom field set

{
  ...
  "_customFieldSet": {
    "customFieldDefinitionId1": "value",
    "customFieldDefinitionId2": "value",
    "customFieldDefinitionId3": "value"
  }
  ...
}

Grouped custom field set

{
  ...
  "_customFieldSet": [
          {
              "_index": "0",
              "customFieldDefinitionId1": "value",
              "customFieldDefinitionId2": "value",
              "customFieldDefinitionId3": "value"
          },
          {
              "_index": "1",
              "customFieldDefinitionId1": "value",
              "customFieldDefinitionId2": "value",
              "customFieldDefinitionId3": "value"
          }
      ]
  ...
}

You can identify any custom field set because the ID starts with an underscore _. To retrieve the custom field values of any object, you must set the detailsLevel query parameter to FULL when making a request. For more information, see Details Level.

You may make PATCH requests to add, replace, or remove a custom field value that you have appropriate access to. We will provide more details on how to perform PATCH requests below. For more information on how access to custom field values is managed, see Custom Fields - Configuring rights for roles.

note

Mambu API v2 PATCH operations respect the RFC6902 standards. We recommend that you use a tool for PATCH generation to avoid syntax mistakes.

Example

Here you can see an example of a standard custom field set with ID _loanPerformanceScore that includes two custom field definitions with IDs amountScore and timeScore and their values.

{
    "id": "ABC001",
    "loanName": "Mortgage Loan",
    "loanState": "PARTIAL_APPLICATION",
    ...
    "_loanPerformanceScore": {    //custom field set
    "amountScore": "10",       //custom field values nested under the set
    "timeScore": "5"
}
}

Here you can see an example of a grouped custom field set with ID _assets and three custom field definitions with IDs asset_age, asset_type, and asset_value and their values.

{
  "encodedKey": "8a19aad43801888d017801f0dd841c1d",
  "id": "190955358",
  "state": "ACTIVE",
  "creationDate": "2021-03-05T11:31:05+01:00",
  "lastModifiedDate": "2022-08-08T12:42:35+02:00",
  "activationDate": "2021-11-18T10:19:13+01:00",
  "approvedDate": "2021-03-05T11:31:05+01:00",
  "firstName": "John ",
  "lastName": "Smith ",
  ...
  "_assets": [  //custom field set
          {     //custom field values in groups nested under the set
              "_index": "0",
              "asset_value": "965000",
              "asset_type": "land",
              "asset_age": "10"
          },
          {
              "_index": "1",
              "asset_value": "25,000",
              "asset_type": "car",
              "asset_age": "2"
          }
      ]
}

Example​

Example