Users API
  • 11 Nov 2020
  • 8 Minutes To Read
  • Print
  • Share
  • Dark
    Light

Users API

  • Print
  • Share
  • Dark
    Light

URL

/api/users

/api/users/{ID}

/api/users/{ID}/custominformation/{customFieldId}

Description

Allows you to retrieve users by their id either a list of users or as one individual user. Note that certain field (like password) are stripped out from the response for security reasons. User custom field values can be changed using patch or delete methods. See Custom Fields API for more information about custom fields and custom fields sets.

Methods

GET, POST, GET Custom Information, PATCH Custom Information, DELETE Custom Information


GET Users

Allows retrieving users directly by a ID/key or through paginating the list of users. Optionally load all nested objects (such as custom fields) for a user as well.

Parameters

fullDetails Whether to load all the nested fields for the users as well (true or false)
branchID The id of the branch to which the user is assigned, filter the user results on. (Optional)
branchIdType How to filter the users based on id. (Optional).
  • ASSIGNED - Returns the users assigned to the branchId. Default value if this parameter is missing
  • MANAGE - Returns the users that can manage the branch(are assigned to the branch, can manage the branch, can manage all branches)

Usage examples

Get the full user details for user demo

GET /api/users/demo

Get the full user details about the user with the encoded key 402832b43809601c013809601f9d0002

GET /api/users/402832b43809601c013809601f9d0002

Get a list of users that are assigned to the branch with id 1

GET /api/users?branchID=1&limit=100&offset=50

Get a list of users that can manage the branch with id 1

GET /api/users?branchID=1&branchIdType=MANAGE

Get the first 100 users from database

GET /api/users?&limit=100&offset=0"

Sample responses:

Sample response of user objects filtered by branch id/key 8a33ae49441c4fe101441c713b36000e

[
   {"
      "encodedKey":"8a33ae49441c4fe101441c5fe42f0005",
      "id":2,
      "creationDate":"2014-02-10T15:17:30+0000",
      "lastModifiedDate":"2014-02-17T12:00:14+0000",
      "lastLoggedInDate":"2014-02-17T12:00:14+0000",
      "username":"demo",
      "email":"fakert@email.com",
      "title":"",
      "firstName":"Max",
      "lastName":"Power",
      "homePhone":"",
      "mobilePhone1":"",
      "language":"ENGLISH",
      "userState":"ACTIVE",
      "twoFactorAuthentication":false,
      "isAdministrator":true,
      "isTeller":false,
      "isCreditOfficer":false,
      "isSupport":false,
      "accessRights":[
         "MAMBU",
         "APIS"
      ],
      "assignedBranchKey":"8a33ae49441c4fe101441c713b36000e",
      "managedBranches":[

      ],
      "notes":"",
      "customFields":[

      ]
   },
   {
      "encodedKey":"8a33ae49441c4fe101441cc6d61a044c",
      "id":3,
      "creationDate":"2014-02-10T17:09:56+0000",
      "lastModifiedDate":"2014-02-11T15:21:49+0000",
      "lastLoggedInDate":"2014-02-11T15:21:49+0000",
      "username":"test",
      "email":"",
      "title":"",
      "firstName":"new",
      "lastName":"",
      "homePhone":"",
      "mobilePhone1":"",
      "language":"ENGLISH",
      "userState":"ACTIVE",
      "twoFactorAuthentication":false,
      "isAdministrator":false,
      "isTeller":true,
      "isCreditOfficer":false,
      "isSupport":false,
      "accessRights":[
         "MAMBU",
         "APIS"
      ],
      "assignedBranchKey":"8a33ae49441c4fe101441c713b36000e",
      "managedBranches":[

      ],
      "notes":"",
      "customFields":[

      ]
   }
]

Sample response of a user object without full details

{
   "encodedKey":"8a54e5b4443e9c9401444084b555000b",
   "id":51,
   "creationDate":"2014-02-17T15:44:02+0000",
   "lastModifiedDate":"2014-02-17T15:46:04+0000",
   "username":"api",
   "email":"fake_user@mail.com",
   "title":"",
   "firstName":"API",
   "lastName":"User",
   "homePhone":"532323",
   "mobilePhone1":"1234456",
   "language":"ENGLISH",
   "userState":"ACTIVE",
   "twoFactorAuthentication":true,
   "isAdministrator":false,
   "isTeller":false,
   "isCreditOfficer":false,
   "isSupport":false,
   "accessRights":[
      "MAMBU",
      "APIS"
   ],
   "assignedBranchKey":"8a33ae49441c4fe101441c713b36000e",
   "managedBranches":[

   ],
   "notes":"User used of API testing"
}

Sample response of a user object with full details

{
   "encodedKey":"8a54e5b4443e9c9401444084b555000b",
   "id":51,
   "creationDate":"2014-02-17T15:44:02+0000",
   "lastModifiedDate":"2014-02-17T15:46:04+0000",
   "permissions":{
      "encodedKey":"8a54e5b4443e9c9401444084b587000c",
      "permissions":[
         "MANAGE_MAMBU_USERS",
         "VIEW_USER_DETAILS",
         "SUBSITUTE_USER",
         "EXIT_CLIENT",
         "BLACKLIST_CLIENT",
         "UNDO_CLIENT_STATE_CHANGED",
         "EDIT_CLIENT_ID",
         "VIEW_GROUP_DETAILS",
         "STORE_GROUP",
         "DELETE_GROUP",
         "VIEW_LOAN_ACCOUNT_DETAILS",
         "STORE_LOAN_ACCOUNT",
         "ENTER_REPAYMENT",
         "EDIT_REPAYMENT_SCHEDULE",
         "VIEW_SAVINGS_ACCOUNT_DETAILS",
         "STORE_SAVINGS_ACCOUNT",
         "MAKE_DEPOSIT",
         "MAKE_WITHDRAWAL",
         "MAKE_EARLY_WITHDRAWALS",
         "DELETE_SAVINGS_TRANSACTION",
         "APPROVE_SAVINGS",
         "CLOSE_SAVINGS_ACCOUNTS",
         "APPLY_SAVINGS_FEES",
         "REOPEN_SAVINGS_ACCOUNT",
         "APPLY_SAVINGS_ADJUSTMENTS",
         "LOCK_SAVINGS_ACCOUNT",
         "UNLOCK_SAVINGS_ACCOUNT",
         "REVERSE_SAVINGS_ACCOUNT_WRITE_OFF",
         "BACKDATE_SAVINGS_TRANSACTIONS",
         "DELETE_SAVINGS_ACCOUNT",
         "MAKE_TRANSFER"
      ],
      "canManageAllBranches":true
   },
   "username":"api",
   "email":"fake_user@mail.com",
   "title":"",
   "firstName":"API",
   "lastName":"User",
   "homePhone":"532323",
   "mobilePhone1":"1234456",
   "language":"ENGLISH",
   "userState":"ACTIVE",
   "twoFactorAuthentication":true,
   "isAdministrator":false,
   "isTeller":false,
   "isCreditOfficer":false,
   "isSupport":false,
   "accessRights":[
      "MAMBU",
      "APIS"
   ],
   "assignedBranchKey":"8a33ae49441c4fe101441c713b36000e",
   "managedBranches":[

   ],
   "notes":"User used of API testing
",
   "customFields":[
      {
         "encodedKey":"8a54e5b4443e9c940144408690270013",
         "parentKey":"8a54e5b4443e9c9401444084b555000b",
         "customFieldKey":"8a54e5b4443e9c9401444085e75e0012",
         "customField":{
            "encodedKey":"8a54e5b4443e9c9401444085e75e0012",
            "id":"ucf",
            "name":"user_cf",
            "type":"USER_INFO",
            "dataType":"STRING",
            "valueLength":"SHORT",
            "isDefault":false,
            "isRequired":false,
            "description":"",
            "customFieldSet":{
               "encodedKey":"8a54e5b4443e9c94014440858e350011",
               "name":"User_CS",
               "notes":"",
               "createdDate":"2014-02-17T15:44:58+0000",
               "indexInList":0,
               "type":"USER_INFO"
            },
            "indexInList":0,
            "state":"NORMAL"
         },
         "value":"some dummy data",
         "indexInList":-1
      }
   ]
}
Please be Aware
For a more flexible filtering of users it is possible to create custom views and call them using the custom views API.

PATCH User Custom Field Values

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

Parameters for PATCH custom fields method for user

value New value for custom field. Required.
customFieldID The id of the custom field to be edited. Required when editing multiple.
customFieldSetGroupIndex The index of the custom field set to be edited. If it isn't provided, a new set is added.
Please be Aware
Date custom fields are currently date only, not date-time.

Usage Example

Update the custom field value to 10 based on the user id abc123 and on the custom field id members

PATCH /api/users/abc123/custominformation/members
{
    "value": "10"
}

Update the custom field value to 2012-10-10 based on the user key 40288a134887e7e9014887f0eb720003 and on the custom field key 8a27a878491d417601491d48203100d9

PATCH /api/users/40288a134887e7e9014887f0eb720003/custominformation/8a27a878491d417601491d48203100d9
{
    "value": "2012-10-10"
}

Update (add / edit) multiple grouped and/or standard fields from different groups for the user with the id 1111.

Please Note
For a grouped custom field, if customFieldSetGroupIndex is present, the value is updated; if it is missing, a new group is created.
PATCH /api/users/1111/custominformation/
{
  "customInformation": [
    {
      "customFieldID" : "IBAN",
      "value" : "DE123456789121243546783"
    },
    {
      "customFieldID" : "BIC",
      "value" : "1234566441",
      "customFieldSetGroupIndex" : "0"
    },
    {
      "customFieldID" : "BANK_ACCOUNT_TYPE",
      "value" : "Current Account",
      "customFieldSetGroupIndex" : "1"
    }
  ]
}

Response

A 200 Response is returned if the user custom field value was successfully created/updated.


GET User Custom Field Values

Allows retrieving a custom field value for a given user directly by the ID/key of the user and the ID/key of the custom field.

Usage Example

Get the custom field value of the custom field with the ID family_members for the user having ID abc123

GET /api/users/abc123/custominformation/family_members

Get the custom field value of the custom field with the encoded key 8a8080a254a98efe0154a99ad86f00ef for the user having key 8a8080a254a98efe0154a99ad8c400f6

GET /api/users/8a8080a254a98efe0154a99ad8c400f6/custominformation/8a8080a254a98efe0154a99ad86f00ef

Response

Response for a single custom field

[
  {
    "encodedKey": "8a8080a254a98efe0154a99ad9d301be",
    "parentKey": "8a8080a254a98efe0154a99ad8c400f6",
    "customFieldKey": "8a8080a254a98efe0154a99ad86f00ef",
    "customField": {
      "encodedKey": "8a8080a254a98efe0154a99ad86f00ef",
      "id": "Position_Clients",
      "creationDate": "2016-05-18T14:39:13+0000",
      "lastModifiedDate": "2016-05-18T14:40:19+0000",
      "name": "Position",
      "type": "USER_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254a98efe0154a99ad84200ee",
        "name": "Custom Fields",
        "createdDate": "2016-05-13T10:12:58+0000",
        "indexInList": 0,
        "type": "USER_INFO",
        "usage": "SINGLE"
      },
      "indexInList": 3,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254a98efe0154a99ad87200f0",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254a98efe0154a99ad87300f1",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "Promotions manager",
    "indexInList": 0,
    "customFieldID": "Position_Clients",
    "customFieldSetGroupIndex": -1
  }
]

Response for a grouped custom field

[
  {
    "encodedKey": "8a8080a254c4397d0154c450f88d0034",
    "parentKey": "8a8080a254a98efe0154a99ad8c800fa",
    "customFieldKey": "8a8080a254c4397d0154c45093f4002a",
    "customField": {
      "encodedKey": "8a8080a254c4397d0154c45093f4002a",
      "id": "ccc1",
      "creationDate": "2016-05-18T14:41:36+0000",
      "lastModifiedDate": "2016-05-18T14:41:36+0000",
      "name": "cccc1",
      "type": "USER_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254c4397d0154c450633e0029",
        "name": "groupedcfs",
        "notes": "",
        "createdDate": "2016-05-18T14:41:23+0000",
        "indexInList": 2,
        "type": "USER_INFO",
        "usage": "GROUPED"
      },
      "indexInList": 14,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002b",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002c",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "111",
    "indexInList": 0,
    "customFieldID": "ccc1",
    "customFieldSetGroupIndex": 0
  },
  {
    "encodedKey": "8a8080a254c4397d0154c4545f410037",
    "parentKey": "8a8080a254a98efe0154a99ad8c800fa",
    "customFieldKey": "8a8080a254c4397d0154c45093f4002a",
    "customField": {
      "encodedKey": "8a8080a254c4397d0154c45093f4002a",
      "id": "ccc1",
      "creationDate": "2016-05-18T14:41:36+0000",
      "lastModifiedDate": "2016-05-18T14:41:36+0000",
      "name": "cccc1",
      "type": "USER_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254c4397d0154c450633e0029",
        "name": "groupedcfs",
        "notes": "",
        "createdDate": "2016-05-18T14:41:23+0000",
        "indexInList": 2,
        "type": "USER_INFO",
        "usage": "GROUPED"
      },
      "indexInList": 14,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002b",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002c",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "222",
    "indexInList": 2,
    "customFieldID": "ccc1",
    "customFieldSetGroupIndex": 1
  },
  {
    "encodedKey": "8a8080a254c4397d0154c4545f410039",
    "parentKey": "8a8080a254a98efe0154a99ad8c800fa",
    "customFieldKey": "8a8080a254c4397d0154c45093f4002a",
    "customField": {
      "encodedKey": "8a8080a254c4397d0154c45093f4002a",
      "id": "ccc1",
      "creationDate": "2016-05-18T14:41:36+0000",
      "lastModifiedDate": "2016-05-18T14:41:36+0000",
      "name": "cccc1",
      "type": "USER_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254c4397d0154c450633e0029",
        "name": "groupedcfs",
        "notes": "",
        "createdDate": "2016-05-18T14:41:23+0000",
        "indexInList": 2,
        "type": "USER_INFO",
        "usage": "GROUPED"
      },
      "indexInList": 14,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002b",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002c",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "333",
    "indexInList": 4,
    "customFieldID": "ccc1",
    "customFieldSetGroupIndex": 2
  }
]

POST Users

Allows the creation of a user using a predefined role.

Please Note
If federated authentication is enabled, user creation is available only if the Role associated with the created user has API-only access rights.

Parameters for Users

username User identifier used for accessing Mambu. Required. *
password User's password. Must respect security restrictions defined in Mambu. Required. *
role
encodedKey The encoded key of the role to create the user with Required. *
permissions
canManageAllBranches Boolean. States whether the user has access to all the branches in the application. Required
canManageEntitiesAssignedToOtherOfficers Boolean. States whether the user has access to entities assigned to other credit officers. Required
firstName User's first name. Required. *
lastName User's last name.
title User's title (Eg. Mr.).
language User's language, defaults to ENGLISH if not specified (Some example values: PORTUGESE, SPANISH, RUSSIAN, FRENCH, GEORGIAN, CHINESE, INDONESIAN, ROMANIAN).
assignedBranchKey User's assigned branch (encodedKey). Is mandatory the user is a teller or credit officer.
email User's email address. Must be valid.
homePhone User's home phone.
mobilePhone1 User's mobile phone number.
twoFactorAuthentication Boolean value for whether the user will use two factor authentication when logging in the application.
managedBranches List of user's managed branched (with encoded keys).
transactionLimits Map of specifying user transaction limits. Valid transaction limit types are: APPROVE_LOAN, DISBURSE_LOAN, APPLY_FEE, MAKE_DEPOSIT, MAKE_WITHDRAWAL, MAKE_REPAYMENT.
notes Notes for the user to be created.
customInformation List of custom field values for the user to be created.

Usage Example

Create user using JSON

POST api/users
{
   "user":{
      "username":"myUserName",
      "password":"complicatedPassword",
      "role":{
         "encodedKey":"ff8080815843175f015843192dac0001"
      },
      "permissions":{
         "canManageAllBranches":"false",
         "canManageEntitiesAssignedToOtherOfficers":"false"
      },
      "email":"valid@email.com",
      "title":"Mr.",
      "firstName":"MandatoryFirstName",
      "lastName":"John",
      "homePhone":"1234567890",
      "mobilePhone1":"1234567890",
      "language":"ENGLISH",
      "userState":"ACTIVE",
      "twoFactorAuthentication":false,
      "notes":"notes"
   },
   "customInformation":[
      {
         "value":"yes",
         "customFieldID":"isTechnical"
      }
   ]
}

Response

A 201 Response is returned if the user was successfully created. The response Location header is set to the user id and the created user is also returned.

{
   "user":{
      "encodedKey":"ff8080815843481b015843481b9b0000",
      "id":141,
      "creationDate":"2016-11-08T09:32:25+0000",
      "lastModifiedDate":"2016-11-08T09:32:25+0000",
      "permissions":{
         "encodedKey":"ff8080815843481b015843481baf0001",
         "permissions":[
            "VIEW_COMMENTS"
         ],
         "canManageAllBranches":true,
         "canManageEntitiesAssignedToOtherOfficers":true
      },
      "role":{
         "encodedKey":"ff8080815843175f015843192dac0001"
      },
      "username":"myUserName",
      "email":"valid@email.com",
      "title":"Mr.",
      "firstName":"MandatoryFirstName",
      "lastName":"John",
      "homePhone":"1234567890",
      "mobilePhone1":"1234567890",
      "language":"ENGLISH",
      "userState":"ACTIVE",
      "twoFactorAuthentication":false,
      "isAdministrator":false,
      "isTeller":false,
      "isCreditOfficer":true,
      "isSupport":false,
      "accessRights":[

      ],
      "assignedBranchKey":"8afae5fb3c52a564013c589a4a047a1d",
      "managedBranches":[

      ],
      "notes":"notes",
      "failedLoginsCount":0
   },
   "customInformation":[
      {
         "encodedKey":"ff8080815843481b015843481c380004",
         "parentKey":"ff8080815843481b015843481b9b0000",
         "customFieldKey":"ff80808157ada4060157ada7c3870074",
         "customField":{
            "encodedKey":"ff80808157ada4060157ada7c3870074",
            "id":"isTechnical",
            "creationDate":"2016-10-10T08:13:55+0000",
            "lastModifiedDate":"2016-10-10T08:13:55+0000",
            "name":"Is Technical",
            "type":"USER_INFO",
            "dataType":"STRING",
            "valueLength":"SHORT",
            "isDefault":false,
            "isRequired":false,
            "description":"",
            "customFieldSet":{
               "encodedKey":"ff80808157ada4060157ada7a5200073",
               "name":"MySet",
               "notes":"desc",
               "createdDate":"2016-10-10T08:13:48+0000",
               "indexInList":0,
               "type":"USER_INFO",
               "usage":"SINGLE"
            },
            "indexInList":0,
            "state":"NORMAL",
            "customFieldSelectionOptions":[

            ],
            "viewRights":{
               "encodedKey":"ff80808157ada4060157ada7c3900075",
               "isAccessibleByAllUsers":false,
               "roles":[

               ]
            },
            "editRights":{
               "encodedKey":"ff80808157ada4060157ada7c3910076",
               "isAccessibleByAllUsers":false,
               "roles":[

               ]
            },
            "unique":false,
            "values":[

            ],
            "amounts":{

            }
         },
         "value":"yes",
         "indexInList":-1,
         "customFieldID":"isTechnical",
         "customFieldSetGroupIndex":-1
      }
   ]
}

DELETE User Custom Field Values

Specific custom field values for a user can be deleted based on user id and custom field id.

Usage Example

DELETE the custom field value based on the user id abc123 and on the custom field id members

DELETE /api/users/abc123/custominformation/members

DELETE the custom field value based on the user key 40288a134887e7e9014887f0eb720003 and on the custom field key 8a27a878491d417601491d48203100d9

DELETE /api/users/40288a134887e7e9014887f0eb720003/custominformation/8a27a878491d417601491d48203100d9`
Please Note
To DELETE a custom field value from a custom field in a group custom field set, the group index of the custom field must included in the call:
DELETE /api/users/USER_ID/custominformation/CF_ID/GROUP_INDEX

Response

A 200 Response is returned if the user custom field value was successfully deleted.


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?