Custom Fields API
  • Updated on 12 Feb 2020
  • 7 minutes to read
  • Print
  • Share
  • Dark
    Light

Custom Fields API

  • Print
  • Share
  • Dark
    Light

URL

/api/customfields/{customFieldId}

/api/customfieldsets

Description

Allows you to retrieve the defined custom fields and custom field sets. A custom field set can contain custom fields.

Populating custom fields

Custom fields are attached to an entity, and need to be populated as part of a post to such entity. In Mambu custom fields can be created, in the user interface, for:

  • Clients

  • Groups

  • Loans

  • Loan Transactions

  • Savings

  • Savings Transactions

  • Branches

  • Centres

  • Users

Custom field sets

Custom fields can be grouped by sets. Mambu uses the parameter customFieldSetGroupIndex to refer to a custom field set. The index is consecutive, starts in index 0 and corresponds, in order, to the list of custom fields returned when querying the identity. Currently custom fields cannot be created via API.

{
    "customInformation":[
       {
          "value":"1",
          "customFieldID":"Family_Members",
          "customFieldSetGroupIndex":"0"
       },
       {
          "value":"TRUE",
          "customFieldID":"Has_children",
          "customFieldSetGroupIndex":"1"
       }
    ]
}

Checkbox-type custom fields

When editing or creating a checkbox-type custom field, the value needs to be specified as "TRUE" or "FALSE" .

Get details of a client who has a checkbox type custom field

expand example...

GET /api/clients/ABC123

{
    "client": {...},
    "addresses": [],
    "customInformation": [
        {
            "encodedKey": "8a808608703847f7017039fc567800be",
            "parentKey": "8a8087c26f75bf47016f7a7a06d100c6",
            "customFieldKey": "8a808608703847f7017039d066ae00ba",
            "customField": {
                "encodedKey": "8a808608703847f7017039d066ae00ba",
                "id": "CHKBX",
                "creationDate": "2020-02-12T14:41:27+0000",
                "lastModifiedDate": "2020-02-12T14:45:44+0000",
                "name": "Likes Marmite",
                "type": "CLIENT_INFO",
                "dataType": "CHECKBOX",
                "valueLength": "SHORT",
                "isDefault": false,
                "isRequired": false,
                "description": "Checkbox offering options of 'Yes' or 'No' in the UI. In this example we have a field to record whether the client loves or hates the polarising, sticky, dark brown, yeast extract-based food spread, marmite",
                "customFieldSet": {
                    "encodedKey": "8a80874c6fd32299016fd744c6983843",
                    "id": "_CF_TEST_01",
                    "name": "Custom Fields",
                    "notes": "",
                    "createdDate": "2020-01-24T12:50:24+0000",
                    "lastModifiedDate": "2020-01-24T12:50:24+0000",
                    "indexInList": 2,
                    "type": "CLIENT_INFO",
                    "usage": "GROUPED"
                },
                "indexInList": 12,
                "state": "NORMAL",
                "customFieldSelectionOptions": [],
                "viewRights": {
                    "encodedKey": "8a808608703847f7017039d066ae00bb",
                    "isAccessibleByAllUsers": false,
                    "roles": []
                },
                "editRights": {
                    "encodedKey": "8a808608703847f7017039d066ae00bc",
                    "isAccessibleByAllUsers": false,
                    "roles": []
                },
                "unique": false,
                "values": [],
                "amounts": {}
            },
            "value": "FALSE",
            "indexInList": -1,
            "customFieldID": "CHKBX",
            "customFieldSetGroupIndex": 0
        }
    ],
    "idDocuments": [],
    "notificationTemplates": [],
    "groupKeys": []
}

Add custom field and mark checkbox as 'no'

POST /api/loans/MBM8392 
{
    "client": {...},
    "customInformation": [
        {
        "value":"FALSE",
        "customFieldID":"checboxCustomFieldID",
        }
    ]
}
Please note
The field type is string so values must be supplied as either "TRUE" or "FALSE" enclosed in quotation marks and not as a boolean.

Linked custom fields

When editing a custom field which provides a link to a client, group, or user, this link can be specified using the linkedEntityKeyValue field as in the examples below.

Please Note
The recommended method instead for such updates, available for all types of custom fields, is by sending the "value" field as demonstrated in these examples.

Get Client with Linked Custom Fields

expand example ...

GET /api/clients/653563750?fullDetails=true

    {
    "client": {...},
    "addresses": [],
    "customInformation": [
        {
            "encodedKey": "8a808608703847f7017039cfe35800b4",
            "parentKey": "8a8087c26f75bf47016f7a7a06d100c6",
            "customFieldKey": "8a808608703847f70170391f25190043",
            "customField": {
                "encodedKey": "8a808608703847f70170391f25190043",
                "id": "LNKED_ENT_CLI",
                "creationDate": "2020-02-12T14:28:42+0000",
                "lastModifiedDate": "2020-02-12T14:48:28+0000",
                "name": "linked client entity",
                "type": "CLIENT_INFO",
                "dataType": "CLIENT_LINK",
                "valueLength": "SHORT",
                "isDefault": false,
                "isRequired": false,
                "description": "Custom Field which will link this client to another. This kind of field can be used to create relationships between clients, for example, linking the accounts of minors to their legal guardian, who may have an account at the same bank",
                "customFieldSet": {
                    "encodedKey": "8a80874c6fd32299016fd744c6983843",
                    "id": "_CF_TEST_01",
                    "name": "Custom Fields",
                    "notes": "",
                    "createdDate": "2020-01-24T12:50:24+0000",
                    "lastModifiedDate": "2020-01-24T12:50:24+0000",
                    "indexInList": 2,
                    "type": "CLIENT_INFO",
                    "usage": "GROUPED"
                },
                "indexInList": 9,
                "state": "NORMAL",
                "customFieldSelectionOptions": [],
                "viewRights": {
                    "encodedKey": "8a808608703847f70170391f25190044",
                    "isAccessibleByAllUsers": false,
                    "roles": []
                },
                "editRights": {
                    "encodedKey": "8a808608703847f70170391f25190045",
                    "isAccessibleByAllUsers": false,
                    "roles": []
                },
                "unique": false,
                "values": [],
                "amounts": {}
            },
            "linkedEntityKeyValue": "8a8087c26f75bf47016f7a7b236900ca",
            "indexInList": -1,
            "customFieldID": "LNKED_ENT_CLI",
            "customFieldSetGroupIndex": 0
        },
        {
            "encodedKey": "8a808608703847f7017039cfe35800b6",
            "parentKey": "8a8087c26f75bf47016f7a7a06d100c6",
            "customFieldKey": "8a808608703847f7017039cd50d000ab",
            "customField": {
                "encodedKey": "8a808608703847f7017039cd50d000ab",
                "id": "LNKED_ENT_GRP",
                "creationDate": "2020-02-12T14:29:09+0000",
                "lastModifiedDate": "2020-02-12T14:46:48+0000",
                "name": "linked group entity",
                "type": "CLIENT_INFO",
                "dataType": "GROUP_LINK",
                "valueLength": "SHORT",
                "isDefault": false,
                "isRequired": false,
                "description": "Custom Field to link this client to a group",
                "customFieldSet": {
                    "encodedKey": "8a80874c6fd32299016fd744c6983843",
                    "id": "_CF_TEST_01",
                    "name": "Custom Fields",
                    "notes": "",
                    "createdDate": "2020-01-24T12:50:24+0000",
                    "lastModifiedDate": "2020-01-24T12:50:24+0000",
                    "indexInList": 2,
                    "type": "CLIENT_INFO",
                    "usage": "GROUPED"
                },
                "indexInList": 10,
                "state": "NORMAL",
                "customFieldSelectionOptions": [],
                "viewRights": {
                    "encodedKey": "8a808608703847f7017039cd50d000ac",
                    "isAccessibleByAllUsers": false,
                    "roles": []
                },
                "editRights": {
                    "encodedKey": "8a808608703847f7017039cd50d000ad",
                    "isAccessibleByAllUsers": false,
                    "roles": []
                },
                "unique": false,
                "values": [],
                "amounts": {}
            },
            "linkedEntityKeyValue": "8a8087c26f75bf47016f7a7e47ff00d8",
            "indexInList": -1,
            "customFieldID": "LNKED_ENT_GRP",
            "customFieldSetGroupIndex": 0
        },
        {
            "encodedKey": "8a808608703847f7017039cfe35800b8",
            "parentKey": "8a8087c26f75bf47016f7a7a06d100c6",
            "customFieldKey": "8a808608703847f7017039ce0e9f00af",
            "customField": {
                "encodedKey": "8a808608703847f7017039ce0e9f00af",
                "id": "LNKED_ENT_USR",
                "creationDate": "2020-02-12T14:29:30+0000",
                "lastModifiedDate": "2020-02-12T14:43:34+0000",
                "name": "linked user entity",
                "type": "CLIENT_INFO",
                "dataType": "USER_LINK",
                "valueLength": "SHORT",
                "isDefault": false,
                "isRequired": false,
                "description": "Field to link this client to another user of the mambu system. This can be used to, for example, subscribe this user to automated notifications based on account activity or provide an alternate point of contact in the case their account manager is OOO",
                "customFieldSet": {
                    "encodedKey": "8a80874c6fd32299016fd744c6983843",
                    "id": "_CF_TEST_01",
                    "name": "Custom Fields",
                    "notes": "",
                    "createdDate": "2020-01-24T12:50:24+0000",
                    "lastModifiedDate": "2020-01-24T12:50:24+0000",
                    "indexInList": 2,
                    "type": "CLIENT_INFO",
                    "usage": "GROUPED"
                },
                "indexInList": 11,
                "state": "NORMAL",
                "customFieldSelectionOptions": [],
                "viewRights": {
                    "encodedKey": "8a808608703847f7017039ce0e9f00b0",
                    "isAccessibleByAllUsers": false,
                    "roles": []
                },
                "editRights": {
                    "encodedKey": "8a808608703847f7017039ce0e9f00b1",
                    "isAccessibleByAllUsers": false,
                    "roles": []
                },
                "unique": false,
                "values": [],
                "amounts": {}
            },
            "linkedEntityKeyValue": "8a80877d6f451a5c016f466bd0ea0043",
            "indexInList": -1,
            "customFieldID": "LNKED_ENT_USR",
            "customFieldSetGroupIndex": 0
        }
    ],
    "idDocuments": [],
    "notificationTemplates": [],
    "groupKeys": []
}

Create link between clients using a linked entity custom field

POST /api/loans/MBM8392

{
    "client": {...},
    "customInformation": [
        {
        "linkedEntityKeyValue": "40228ab578f90bc38b6700a",
        "customFieldID": "Income"
        }
    ]
}

Update the custom field value to point to client with key 8a8087205e748c8f015e74f111290423

PATCH /api/clients/CLIENT_ID/custominformation/CLIENT_LINK_CF_ID

{ 
   "linkedEntityKeyValue": "8a8087205e748c8f015e74f111290423"
}

Methods

GET, PATCH, DELETE


GET Custom Fields

Allows retrieving of a custom field based on id/key. The custom field can be fetched only based on id/key.

General Usage examples

Get the custom field with JOB_TITLE id

GET /api/customfields/JOB_TITLE

Get the custom field with 8a54e5b44449337 encoded key

GET /api/customfields/8a54e5b44449337

Sample responses

Response containing the custom field with JOB_TITLE id

{
    "encodedKey":"8a54e5b44449337f01444a6db5d40006",
    "id":"JOB_TITLE",
    "name":"Current Job Title",
    "type":"CLIENT_INFO",
    "dataType":"STRING",
    "valueLength":"LONG",
    "isDefault":true,
    "isRequired":true,
    "description":"The current job title for the client.",
    "indexInList":8,
    "state":"NORMAL"
}

Get information about an account with dependant custom fields (constraint) section

{
   "encodedKey":"8abcd7a84b7cb5a1014b7d3d18de019d",
   "id":"Selection_Clients",
   "name":"Selection",
   "type":"CLIENT_INFO",
   "dataType":"SELECTION",
   "valueLength":"SHORT",
   "isDefault":false,
   "isRequired":false,
   "description":"The current job title for the client.",
   "indexInList":8,
   "state":"NORMAL",
   "customFieldSelectionOptions":[
      {
         "encodedKey":"40288a134b9c2ff3014b9cf8573c03f6",
         "id": "024844659",
         "value":"Berlin",
         "score":"12",
         "constraint":{
            "encodedKey":"40288a134b9c2ff3014b9cf8573c03f7",
            "dataFieldType":"CUSTOM",
            "dataItemType":"CLIENT",
            "dataType":"STRING",
            "customFieldKey":"40288a134b9c2ff3014b9cf7850c03f0",
            "filterElement":"EQUALS",
            "value":"40288a134b9c2ff3014b9cf7851003f2",
            "linkingOperator":"AND"
         }
      },
      {
         "encodedKey":"40288a134b9c2ff3014b9cf8573d03f8",
         "id": "035955760",
         "value":"Frankfurt",
         "constraint":{
            "encodedKey":"40288a134b9c2ff3014b9cf8573d03f9",
            "dataFieldType":"CUSTOM",
            "dataItemType":"CLIENT",
            "dataType":"STRING",
            "customFieldKey":"40288a134b9c2ff3014b9cf7850c03f0",
            "filterElement":"EQUALS",
            "value":"40288a134b9c2ff3014b9cf7851003f2",
            "linkingOperator":"AND"
         }
      }
   ]
}

Entity-specific Articles

Please see the appropriate article below for additional information


GET Custom Field Sets

Allows retrieving of a list custom field sets that can be optionaly filtered by type.

Parameters

type The custom field set type. Posible values:
  • CLIENT_INFO
  • GROUP_INFO
  • LOAN_ACCOUNT_INFO
  • SAVINGS_ACCOUNT_INFO
  • BRANCH_INFO
  • CENTRE_INFO
  • USER_INFO
  • LINE_OF_CREDIT

Usage examples

Get all custom field sets

GET /api/customfieldsets

Get all USER_INFO type custom field sets

GET /api/customfieldsets?type=USER_INFO

Sample responses

Response containing the custom field sets for USER_INFO type

[
   {
      "encodedKey":"8a54e5b4443e9c94014440858e350011",
      "name":"User_CS",
      "notes":"",
      "createdDate":"2014-02-17T15:44:58+0000",
      "indexInList":0,
      "type":"USER_INFO",
      "customFields":[
         {
            "encodedKey":"8a54e5b4443e9c9401444085e75e0012",
            "id":"ucf",
            "name":"user_cf",
            "type":"USER_INFO",
            "dataType":"STRING",
            "valueLength":"SHORT",
            "isDefault":false,
            "isRequired":false,
            "description":"",
            "indexInList":0,
            "state":"NORMAL"
         },
         {
            "encodedKey":"8a54e5b44449337f01444a8402930007",
            "id":"IP",
            "name":"Internal Position",
            "type":"USER_INFO",
            "dataType":"SELECTION",
            "valueLength":"SHORT",
            "isDefault":true,
            "isRequired":true,
            "values":[
               "Manager",
               "Developer"
            ],
            "amounts":{
               "Manager":"1",
               "Developer":"2"
            },
            "description":"",
            "indexInList":1,
            "state":"NORMAL"
         }
      ]
   },
   {
      "encodedKey":"8a54e5b44449337f01444a84a5640008",
      "name":"Emprt User CFS",
      "notes":"User Custom Field Set",
      "createdDate":"2014-02-19T14:20:10+0000",
      "indexInList":1,
      "type":"USER_INFO",
      "customFields":[

      ]
   }
]

Response containing the custom field sets for LOAN_ACCOUNT_INFO type. If a productKey field is present then the custom field set is assigned to a loan product.

[
   {
      "encodedKey":"8a54e5b4444e245501444f3bab160538",
      "name":"Loan Product CFS",
      "notes":"Custom field set for agriculture loan product",
      "createdDate":"2014-02-20T12:18:34+0000",
      "indexInList":0,
      "type":"LOAN_ACCOUNT_INFO",
      "customFields":[
         {
            "encodedKey":"8a54e5b4444e245501444f3df73c0539",
            "id":"T_C_F_A_L",
            "name":"Test Custom Field Agriculutre Loan",
            "type":"LOAN_ACCOUNT_INFO",
            "dataType":"STRING",
            "valueLength":"LONG",
            "isDefault":true,
            "isRequired":true,
            "description":"Test Custom filed for agriculture loan used for internal testing",
            "indexInList":4,
            "state":"NORMAL"
         }
      ],
      "productKey":"8a33ae49441c4fe101441c7154600340"
   }
]

Response containing the custom field sets for LINE_OF_CREDIT type

[
  {
    "encodedKey": "402880b858d95c8e0158d95cfe4b0480",
    "name": "LoC CF Set",
    "notes": "",
    "createdDate": "2016-12-07T12:58:39+0000",
    "indexInList": 0,
    "type": "LINE_OF_CREDIT",
    "customFields": [
      {
        "encodedKey": "402880b858d95c8e0158d95cfe4b0481",
        "id": "loccf1",
        "creationDate": "2016-12-07T12:59:15+0000",
        "lastModifiedDate": "2016-12-07T14:48:17+0000",
        "name": "LoC CF",
        "type": "LINE_OF_CREDIT",
        "dataType": "STRING",
        "valueLength": "SHORT",
        "isDefault": false,
        "isRequired": false,
        "description": "",
        "indexInList": 0,
        "customFieldProductSettings": [],
        "state": "NORMAL",
        "customFieldSelectionOptions": [],
        "viewRights": {
          "encodedKey": "402880b858d95c8e0158d95cfe4b0482",
          "isAccessibleByAllUsers": true,
          "roles": []
        },
        "editRights": {
          "encodedKey": "402880b858d95c8e0158d95dd4a40483",
          "isAccessibleByAllUsers": true,
          "roles": []
        },
        "unique": false,
        "values": [],
        "amounts": {}
      }
    ],
    "usage": "SINGLE"
  }
]

PATCH Custom Field Values

Custom field values for an entity can be added/edited using the PATCH method. The new custom field value is validated based on the custom field type defined in the Custom Field.

Please the see the appropriate article below for further information.


DELETE Custom Field Values

Specific custom field values for an entity can be deleted based on group id and custom field id.

Please the see the appropriate article below for further information.


Ask the Mambu Community
If you have a question about how anything works or have come across something you haven't seen explained here, get in touch with our community of fellow users and Mambuvians where someone will lend a hand.
Ask a question about our REST APIs

* If you don't already have an account you will be prompted to create one when you first visit the site.

Was this article helpful?