Welcome

This documentation was last updated on Mon Sep 12 14:38:30 UTC 2022 and covers Mambu Version v9.127.2

Welcome to the Mambu API 1.0 documentation. Here you can learn everything you need to know about our API and how to interact with Mambu!

About Mambu API 1.0

Scroll down for operations, schemas, example requests and responses.

For more information about API 2.0 vs. API 1.0, please see: our User Guide.

Being RESTful

The Mambu API follows the Representational State Transfer (REST) architectural style allowing resources (accounts, clients, etc) to be viewed, added and modified by a standard set of HTTP methods; GET, POST, PUT, PATCH and DELETE.

Communication with Mambu follows the REST architecture constraints including being stateless & cacheable.

All responses are returned as JSON objects.

Base URL

Mambu tenants can exist either in a multi-tenanted environment with all tenants having access at their own sub-domain or within a dedicated environment.

To make a request to a tenant use the pattern https://TENANT_NAME.mambu.com/api/.

The tenant name will generally be the same as the one used for accessing the Mambu user interface and can also be retrieved by visiting MyMambu and opening the Dashboard tab, where you will also find the domain for your sandbox instance, if this has been activated. See MyMambu in our User Guide for more information on working with MyMambu.

Authentication

Mambu supports two methods for authenticating API requests:

• Basic authentication, using Mambu UI login credentials for a user account with API access permissions.
• API keys, which are unique UUID tokens provided in an apiKey header (Early Access Feature).

Basic Authentication

Example using curl

curl --location --request GET 'https://TENANT_NAME.mambu.com/api/users' \
--header 'Authorization: Basic U29tZVVzZXI6T3BlblNlc2FtZQ=='

For basic authorization, provide your username and password directly via the Authorization header in the format Basic {base64-encoded-string}, where base64-encoded-string is the base-64-encoded value of your username and password separated by a colon ':'.

For example, a user with the username SomeUser and the password OpenSesame would take the value SomeUser:OpenSesame and base-64 encode it, yielding U29tZVVzZXI6T3BlblNlc2FtZQ==. They would then provide an Authorization header for their request with the value Basic U29tZVVzZXI6T3BlblNlc2FtZQ==.

See the example GET requests to the /users endpoint using curl.

Note that the login credentials must be for an account with API access permissions. See API & Apps Authentication in our User Guide for more information.

API Keys

API keys are tokens that you provide in an apiKey header to authenticate requests. They are generated by API consumers, which are an abstraction similar to an OAuth client.

API consumers are currently an Early Access Feature. If you would like to request access to this feature, please get in touch with your Mambu Customer Success Manager to discuss your requirements.

For more information on API consumers and keys, see API Consumers in our User Guide.

Pagination

To customize the response, the offset and limit parameters can be adjusted from their default values.

limit

The default limit for responses is 50. A value of up to 1,000 can be specified with limit.

offset

offset determines how many records will be skipped before being included in the returned results. The default offset value is 0.

Detail Level

Mambu API 1.0 supports two detail levels for responses:

• BASIC -- By default, Mambu API will return the BASIC level of detail. This includes all first level elements of an object.

• FULL -- This detail level includes everything from BASIC as well as all custom fields, any address or contact information, and any other related objects.

To view a higher level of detail, append ?fullDetails=true to the end of the resource URI in your request.

Using the API

Requests

Also referred to as "calls", requests to the Mambu API identify who the requester is and exactly what information they wish to retrieve or which action they wish to perform.

To put together an API Request you will need to combine:

• The HTTP method or "verb"
• The full URI to the resource
• HTTP headers
• The JSON-formatted payload (if required)

Responses

Error Response

{
  "errorCode":"4",
  "errorSource":"Property scheduleSettings.repaymentInstallments may not be null",
  "errorReason":"INVALID_PARAMETERS"
}

Single Resource - JSON object

{
  "field": "value"
}

Collection of Resources - JSON array

[
  {
    "field": "value"
  },
  {
    "field": "value"
  }
]

The response to a request will always be in JSON format and will contain either:

• An error response consisting of:

or

• A JSON representation of the requested resource(s).

User-Agent Header

Error when User Agent header is not provided

{
    "returnCode": 4,
    "returnStatus": "INVALID_PARAMETERS",
    "errorSource": "The user agent cannot be null when the Audit Trail feature is enabled"
}

The User-Agent header provides information regarding the browser and operating system (such as the browser version), and information about the library or tool issuing the request (such as the client Java version). It is generally used to assist with debugging problems.

When the audit trail feature is enabled, you must provide a User-Agent header for all requests to any endpoint, or the request will fail with the described error message. Audit trail tracks all activities performed in the Mambu Core Banking system via the UI, API v1, or API v2. For more information, see Audit Trail in our User Guide.

We recommend providing the user agent header for all calls, even if audit trail is not enabled. For custom integrations, you may wish to provide something like:

User-Agent: custom-integration-name http-client/version.

Note that if you are using a REST client like Postman or Curl, this header is probably provided automatically.

Posting Data

API requests that post data can either use URL-encoded query parameters or a JSON body to enter data. The content-type header must be set to application/json for the JSON request.

The following examples show the two methods for posting data. Note that for some requests, much more information can be posted using the JSON input than is available with query parameters.

Using query parameters

curl -d "type=APPROVAL" https://user:pword@test.mambu.com/api/loans/4028329c3ad6c515013ad6d0f6e40006/transactions

Using JSON:

curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{ "type": "APPROVAL"} https://user:pword@test.mambu.com/api/loans/4028329c3ad6c515013ad6d0f6e40006/transactions`

Example

The following example makes a request using the username user, the password pword to the tenant demo to retrieve all repayments for loan account abc

Request with authorization made ...

https://user:pword@demo.mambu.com/api/loans/abc/repayments

And returns a response such as:

[
    {
        "encodedKey": "402832b4380a2d8801380a9cac860010",
        "parentAccountKey": "402832b4380a2d8801380a9cac41000f",
        "dueDate": "2012-07-28T00:00:00+0200",
        "principalDue": "190",
        "principalPaid": "0",
        "interestDue": "25.45",
        "interestPaid": "0",
        "state": "PENDING"
    },
    {
        "encodedKey": "402832b4380a2d8801380a9cac870011",
        "parentAccountKey": "402832b4380a2d8801380a9cac41000f",
        "dueDate": "2012-08-28T00:00:00+0200",
        "principalDue": "190",
        "principalPaid": "0",
        "interestDue": "26.29",
        "interestPaid": "0",
        "state": "PENDING"
    }
]

Searching and Filtering

Many entities allow you multiple ways to filter your request, either by providing fields and values as query parameters or by using the entity's /search facility. This option is available for: Clients, Groups, Loan Accounts & Loan Transactions, Savings Accounts & Savings Transactions, Notifications, General Ledger Journal Entries and Lines of Credit.

Additionally, the object search API allows you to execute the same search query across multiple types of entity, for example, both loan and savings accounts, or both users and clients, although the number of fields which will be searched is limited.

In each case you will use a POST request and provide your search parameters and sorting preference in the request body, while other constraints, such as the number of records to return, an offset to page through large result sets, or whether you would like full details or only basic data, can be provided as query parameters.

Filter Constraints

Example query with an array of filters on a standard field and a custom field, and a sorting order

{
   "filterConstraints":[
      {
         "filterSelection":"CREATION_DATE",
         "filterElement":"BETWEEN",
         "value":"2015-01-01",
         "secondValue":"2015-06-20"
      },
      {
         "filterSelection":"MY_CUSTOM_FIELD",
         "filterElement":"EQUALS",
         "dataItemType":"CLIENT",
         "dataFieldType":"CUSTOM",
         "value":"BIG spenders"
      }
   ],
   "sortDetails":{
        "sortingColumn":"lastModifiedDate",
        "sortingOrder":"DESCENDING"
    }
}

filterContraints array

sortDetails object

Filter Elements

The table below contains a list of filters available for your search and which types of data you can use them with.

Data Types and Examples

Clients

Get all loan transactions for a specific client

POST /api/clients/search
{
   "filterConstraints":[
      {
         "filterSelection":"ID",
         "filterElement":"EQUALS",
         "dataItemType":"CLIENT",
         "value":"197495342"
      }
   ],
   "sortDetails":{
      "sortingColumn":"ID",
      "sortingOrder":"DESCENDING"
   }
}

Groups

Get all groups created in specific date range

POST /api/groups/search
{
   "filterConstraints":[
      {
         "filterSelection":"CREATION_DATE",
         "filterElement":"BETWEEN",
         "value":"2015-01-01",
         "secondValue":"2015-06-20"
      }
   ]
}

Get all groups that have the custom field with the encoded key 8afac14a34d69cd00134d70c0abe00d3 and value test

POST /api/groups/search
{
   "filterConstraints":[
      {
         "filterSelection":"8afac14a34d69cd00134d70c0abe00d3",
         "filterElement":"EQUALS",
         "value":"test",
         "dataFieldType":"CUSTOM"
      }
   ]
}

Loan Accounts

Get all loans that are in two different products

POST /api/loans/search
{
   "filterConstraints":[
      {
         "filterSelection":"PRODUCT_KEY",
         "filterElement":"IN",
         "values":[
            "ff8080814eaa832d014eaa88e24d034c",
            "ad8080814eaa832d014eaa88e252034e"
         ]
      }
   ]
}

Get all loan accounts created within a date range

POST /api/loans/search
{
   "filterConstraints":[
      {
         "filterSelection":"CREATION_DATE",
         "filterElement":"BETWEEN",
         "value":"2015-06-15",
         "secondValue":"2015-06-20"
      }
   ]
}

Get all loan accounts that have the custom field value test. This custom field is of type string and it belongs to a loan entity

POST /api/loans/search
{
   "filterConstraints":[
      {
         "filterSelection":"8a808085507f02b901507f02f59700ea",
         "filterElement":"EQUALS",
         "value":"test"
      },
      {
         "filterSelection":"CREATION_DATE",
         "dataItemType":"CLIENT",
         "filterElement":"ON",
         "value":"2015-10-19"
      }
   ]
}

Tranches

Get all loan accounts where loan disbursement tranches have been defined but not yet disbursed

POST /api/loans/search
{
   "filterConstraints":[
      {
         "filterSelection":"DISBURSEMENT_TRANSACTION_KEY",
         "dataItemType":"TRANCHE",
         "filterElement":"EMPTY"
      }
   ]
}

Get all loan accounts with a loan disbursement tranche where the amount is 100

POST /api/loans/search
{
   "filterConstraints":[
      {
         "filterSelection":"AMOUNT",
         "dataItemType":"TRANCHE",
         "filterElement":"EQUALS",
         "value":"100"
      }
   ]
}

Disbursement Details

Get all loans disbursed during March 2021

POST /api/loans/search
{
   "filterConstraints":[
      {
         "filterSelection":"DISBURSEMENT_DATE",
         "dataItemType":"DISBURSEMENT_DETAILS",
         "filterElement":"BETWEEN",
         "value":"2021-03-01",
         "secondValue":"2021-03-30"
      }
   ]
}

Savings Accounts

Get all APPROVED and PENDING_APPROVAL savings accounts

POST /api/savings/search
{
   "filterConstraints":[
      {
         "filterSelection":"ACCOUNT_STATE",
         "filterElement":"IN",
         "values":[
            "PENDING_APPROVAL",
            "APPROVED"
         ]
      }
   ]
}

Transactions

Get the repayments transactions for loans that are more than 10 days in arrears

POST /api/loans/transactions/search
{
   "filterConstraints":[
      {
         "filterSelection":"DAYS_IN_ARREARS",
         "filterElement":"MORE_THAN",
         "dataItemType":"LOANS",
         "value":"10"
      },
      {
         "filterSelection":"EVENT",
         "filterElement":"EQUALS",
         "dataItemType":"LOAN_TRANSACTION",
         "value":"REPAYMENT"
      }
   ]
}

Notifications

Get all notification messages for LOAN_CREATED notifications

POST /api/notifications/messages/search
{
   "filterConstraints":[
      {
         "filterSelection":"EVENT",
         "filterElement":"EQUALS",
         "value":"LOAN_CREATED"
      }
   ]
}

General Ledger Journal Entries

Get the journal entry with entry id 1, posted by the user with the encoded key 8a8080a254a9659b0154a965a69a0004

POST /api/gljournalentries/search
{
     "filterConstraints":[
        {
           "filterSelection":"USER_KEY",
           "filterElement":"EQUALS",
           "value":"8a8080a254a9659b0154a965a69a0004"
        },
        {
           "filterSelection":"ENTRY_ID",
           "filterElement":"EQUALS",
           "value":"1"
        }
    ]
}

Lines of Credit

Get all lines of credit identified by state CLOSED

POST /api/linesofcredit/search
{
   "filterConstraints":[
      {
         "filterSelection":"STATE",
         "filterElement":"IN",
         "values":[
            "CLOSED"
         ]
      }
   ]
}

Get all lines of credit identified by exposure limit types APPROVED_AMOUNT and OUTSTANDING_AMOUNT

POST /api/linesofcredit/search
{
   "filterConstraints":[
      {
         "filterSelection":"EXPOSURE_LIMIT_TYPE",
         "filterElement":"IN",
         "values":[
            "APPROVED_AMOUNT","OUTSTANDING_AMOUNT"
         ]
      }
   ]
}

Object Search

Search through all object types for the object that might contain john

GET /api/search?query=john&type=[CLIENT,USER]&limit=10

{
  "CLIENT": [
    {
      "selectionType": "CLIENT",
      "displayString": "John Demo",
      "resultID": "517706810",
      "resultKey": "8a42711a4428c1f101442a1bbcbc0009"
    },
    {
      "selectionType": "CLIENT",
      "displayString": "John Master",
      "resultID": "603117506",
      "resultKey": "8a42711a4428c1f101442a1ee710001b"
    }
  ],
  "CREDIT_OFFICER": [
    {
      "selectionType": "CREDIT_OFFICER",
      "displayString": "johnty billingsworth",
      "resultID": "johntybilling",
      "resultKey": "8a19dab474909bc8017490f2fb9006a8"
    }
  ],
  "USER": [
    {
      "selectionType": "USER",
      "displayString": "John Doe",
      "resultID": "61",
      "resultKey": "8a54e5b44449337f01444b03efa3000e"
    }
  ],
  "SAVINGS_ACCOUNT": [],
  "CUSTOM_FIELD_SELECTION": [],
  "CENTRE": [],
  "FILTER_CUSTOM_FIELD_SELECTION": [],
  "BRANCH": [],
  "LOAN_ACCOUNT": [],
  "GROUP": [],
  "LINE_OF_CREDIT": []
}

Custom View Filtering

Custom views are used to define and display specific groups or subsets of clients, users, loan accounts, and other entities. Examples of custom views include:

• Listing all clients in an active state.
• Listing all loan accounts that are 90 days in arrears.
• Listing all the withdrawal transactions higher than USD700,000.

Custom views may be used to configure tabs and reports in the Mambu UI. Once they are defined, they may also be used to filter requests with the Mambu v1 API. Several GET requests allow filtering the returned results with the criteria defined by an existing custom view. This can be a quick and convenient way to easily filter requests.

For more information on using custom views to filter requests, see Custom Views and API v1 in our User Guide. For general infromation, see Custom Views.

Timezone Offsets

Here is how we handle timezone offsets in API v1 calls:

• We use the following standard date format: ISO_8601_FORMAT_DATE_TIME = "YYYY-MM-DD'T'hh:mm:ss±hh:mm".
• We either save the date as it is or extract the offset value if it contains an offset.
• Unlike in API v2, in API v1 we don’t validate the timezone.

Example

Each Mambu tenant has one timezone. Let’s take for example tenants in the East European time zone (UTC+02:00).

Activities

Allows you to retrieve the activity feed items.

Get all Activities

GET /activities

Get activities

Allows retrieving a list of activities entries within a date range that can be fitered by entity key.

Parameters

Example Responses

200 : OK
An array of activities

[
  {
    "activity": {
      "encodedKey": "8a54e5b444441eba014445e18c640021",
      "transactionID": 1656,
      "timestamp": "2014-02-18T16:43:33+0000",
      "type": "TASK_DELETED",
      "branchKey": "8a33ae49441c4fe101441c713b36000e",
      "userKey": "8a33ae49441c4fe101441c5fe42f0005",
      "assignedUserKey": "8a33ae49441c4fe101441c5fe42f0005",
      "notes": "Disburse your first loan",
      "fieldChanges": []
    },
    "branchName": "Matola City",
    "userName": "Max Power"
  },
  {
    "activity": {
      "encodedKey": "8a54e5b444441eba0144477140920028",
      "transactionID": 1657,
      "timestamp": "2014-02-19T00:00:08+0000",
      "type": "LOAN_ACCOUNT_SET_TO_IN_ARREARS",
      "clientKey": "8a33ae49441c4fe101441c7149e00102",
      "loanProductKey": "8a33ae494420ac160144210c0be50152",
      "loanAccountKey": "8a42711a4430587d0144307a352d0001",
      "notes": "",
      "fieldChanges": []
    },
    "clientName": "Kwemto Akobundu",
    "loanProductName": "dynamic dbei horizontal",
    "loanAccountName": "dynamic dbei horizontal"
  },
  {
    "activity": {
      "encodedKey": "8a54e5b44449337f014449337f130000",
      "transactionID": 1661,
      "timestamp": "2014-02-19T08:11:54+0000",
      "type": "USER_LOGGED_IN",
      "branchKey": "8a33ae49441c4fe101441c713b36000e",
      "userKey": "8a33ae49441c4fe101441c5fe42f0005",
      "assignedUserKey": "8a33ae49441c4fe101441c5fe42f0005",
      "notes": "",
      "fieldChanges": []
    },
    "branchName": "Matola City",
    "userName": "Max Power"
  },
  {
    "activity": {
      "encodedKey": "8a54e5b44449337f0144498ce4430004",
      "transactionID": 1665,
      "timestamp": "2014-02-19T09:49:34+0000",
      "type": "USER_LOGGED_IN",
      "branchKey": "8a33ae49441c4fe101441c713b36000e",
      "userKey": "8a33ae49441c4fe101441c5fe42f0005",
      "assignedUserKey": "8a33ae49441c4fe101441c5fe42f0005",
      "notes": "",
      "fieldChanges": []
    },
    "branchName": "Matola City",
    "userName": "Max Power"
  },
  {
    "activity": {
      "encodedKey": "8a54e5b44449337f014449a978650005",
      "transactionID": 1666,
      "timestamp": "2014-02-19T10:20:47+0000",
      "type": "CLIENT_EDITED",
      "clientKey": "8a33ae49441c4fe101441c71497200e3",
      "userKey": "8a33ae49441c4fe101441c5fe42f0005",
      "notes": "",
      "fieldChanges": [
        {
          "id": 331,
          "fieldChangeName": "NAME",
          "originalValue": "Adaoha Samuel",
          "newValue": "Adaoha z Samuel"
        }
      ]
    },
    "clientName": "Adaoha z Samuel",
    "userName": "Max Power"
  }
]

Responses

Response Schema

Status Code 200

Enumerated Values

Branches

Allows you to retrieve branches which are being used by an organization. For information about custom fields and custom fields sets in branches see Custom Fields API documentation.

Get all Branches

GET /branches

Get all branches

Allows retrieving branches via a paginated list or by using the branch id/key. While using the branch id/key the full details of the branch can be retreived(address, custom fields, holidays). The custom field values can be changed using patch or delete methods.

Parameters

Example Responses

200 : ok
an array of branches with full details

[
  {
    "encodedKey": "8a193c26722b51b701722d779e7122de",
    "id": "demoBranchId",
    "creationDate": "2020-05-19T15:05:23+0000",
    "lastModifiedDate": "2020-09-07T10:44:32+0000",
    "name": "Maputo Downtown",
    "state": "ACTIVE",
    "phoneNumber": "",
    "emailAddress": "",
    "notes": "Is located in the surroundings of the local market with a <i>lot of potential</i> to reach new clients.",
    "branchHolidays": [
      {
        "encodedKey": "8a19df6972b787fc0172b8c473c00b9c",
        "keyId": 12,
        "name": "only maputo holiday day",
        "dayOfMonth": 30,
        "monthOfYear": 7,
        "year": 2020,
        "isAnnualyRecurring": true,
        "creationDate": "2020-06-15T16:17:01+0000"
      }
    ],
    "customFieldValues": [
      {
        "encodedKey": "8a19cd6f74674df9017467f25aab02c6",
        "parentKey": "8a193c26722b51b701722d779e7122de",
        "customFieldKey": "8a19cd6f74674df9017467ef8e6802af",
        "customField": {
          "encodedKey": "8a19cd6f74674df9017467ef8e6802af",
          "id": "cf_branch",
          "creationDate": "2020-09-07T09:42:33+0000",
          "lastModifiedDate": "2020-09-07T09:42:33+0000",
          "name": "Example Custom Field",
          "type": "BRANCH_INFO",
          "dataType": "CHECKBOX",
          "valueLength": "SHORT",
          "isDefault": false,
          "isRequired": false,
          "description": "an example custom field of the checkbox type",
          "customFieldSet": {
            "encodedKey": "8a19cd6f74674df9017467ef8e6802ae",
            "id": "_example_branch_custom_field_set",
            "name": "example branch custom field set",
            "notes": "example custom field set",
            "createdDate": "2020-09-07T09:41:50+0000",
            "lastModifiedDate": "2020-09-07T09:41:50+0000",
            "indexInList": 2,
            "type": "BRANCH_INFO",
            "usage": "SINGLE"
          },
          "indexInList": 0,
          "state": "NORMAL",
          "customFieldSelectionOptions": [],
          "viewRights": {
            "encodedKey": "8a19cd6f74674df9017467ef8e6802b0",
            "isAccessibleByAllUsers": false,
            "roles": []
          },
          "editRights": {
            "encodedKey": "8a19cd6f74674df9017467ef8e6802b1",
            "isAccessibleByAllUsers": false,
            "roles": []
          },
          "unique": false,
          "values": [],
          "amounts": {}
        },
        "value": "TRUE",
        "indexInList": -1,
        "customFieldID": "cf_branch",
        "customFieldSetGroupIndex": -1
      },
      {
        "encodedKey": "8a19cd6f74674df9017468019ac00310",
        "parentKey": "8a193c26722b51b701722d779e7122de",
        "customFieldKey": "8a19cd6f74674df9017467f25aab02c9",
        "customField": {
          "encodedKey": "8a19cd6f74674df9017467f25aab02c9",
          "id": "cf_group_field_1",
          "creationDate": "2020-09-07T09:58:33+0000",
          "lastModifiedDate": "2020-09-07T09:58:33+0000",
          "name": "cf group field 1",
          "type": "BRANCH_INFO",
          "dataType": "STRING",
          "valueLength": "SHORT",
          "isDefault": false,
          "isRequired": false,
          "description": "",
          "customFieldSet": {
            "encodedKey": "8a19cd6f74674df9017467f25aab02c8",
            "id": "_branches_grouped_cf_set",
            "name": "Custom Field Group for Branch",
            "notes": "",
            "createdDate": "2020-09-07T09:47:03+0000",
            "lastModifiedDate": "2020-09-07T09:47:03+0000",
            "indexInList": 3,
            "type": "BRANCH_INFO",
            "usage": "GROUPED"
          },
          "indexInList": 0,
          "state": "NORMAL",
          "customFieldSelectionOptions": [],
          "viewRights": {
            "encodedKey": "8a19cd6f74674df9017467f25aab02ca",
            "isAccessibleByAllUsers": true,
            "roles": []
          },
          "editRights": {
            "encodedKey": "8a19cd6f74674df901746800bdb10307",
            "isAccessibleByAllUsers": true,
            "roles": []
          },
          "unique": false,
          "values": [],
          "amounts": {}
        },
        "value": "group field 1",
        "indexInList": -1,
        "customFieldID": "cf_group_field_1",
        "customFieldSetGroupIndex": 0
      },
      {
        "encodedKey": "8a19cd6f74674df90174681f214103cf",
        "parentKey": "8a193c26722b51b701722d779e7122de",
        "customFieldKey": "8a19cd6f74674df901746800bdb10308",
        "customField": {
          "encodedKey": "8a19cd6f74674df901746800bdb10308",
          "id": "cf_group_field_2",
          "creationDate": "2020-09-07T09:59:02+0000",
          "lastModifiedDate": "2020-09-07T09:59:02+0000",
          "name": "cf group field 2",
          "type": "BRANCH_INFO",
          "dataType": "NUMBER",
          "valueLength": "SHORT",
          "isDefault": false,
          "isRequired": false,
          "description": "",
          "customFieldSet": {
            "encodedKey": "8a19cd6f74674df9017467f25aab02c8",
            "id": "_branches_grouped_cf_set",
            "name": "Custom Field Group for Branch",
            "notes": "",
            "createdDate": "2020-09-07T09:47:03+0000",
            "lastModifiedDate": "2020-09-07T09:47:03+0000",
            "indexInList": 3,
            "type": "BRANCH_INFO",
            "usage": "GROUPED"
          },
          "indexInList": 1,
          "state": "NORMAL",
          "customFieldSelectionOptions": [],
          "viewRights": {
            "encodedKey": "8a19cd6f74674df901746800bdb10309",
            "isAccessibleByAllUsers": true,
            "roles": []
          },
          "editRights": {
            "encodedKey": "8a19cd6f74674df901746800bdb1030a",
            "isAccessibleByAllUsers": true,
            "roles": []
          },
          "unique": false,
          "values": [],
          "amounts": {}
        },
        "value": "2",
        "indexInList": -1,
        "customFieldID": "cf_group_field_2",
        "customFieldSetGroupIndex": 0
      },
      {
        "encodedKey": "8a19cd6f74674df90174681f214103d1",
        "parentKey": "8a193c26722b51b701722d779e7122de",
        "customFieldKey": "8a19cd6f74674df901746800bdb10308",
        "customField": {
          "encodedKey": "8a19cd6f74674df901746800bdb10308",
          "id": "cf_group_field_2",
          "creationDate": "2020-09-07T09:59:02+0000",
          "lastModifiedDate": "2020-09-07T09:59:02+0000",
          "name": "cf group field 2",
          "type": "BRANCH_INFO",
          "dataType": "NUMBER",
          "valueLength": "SHORT",
          "isDefault": false,
          "isRequired": false,
          "description": "",
          "customFieldSet": {
            "encodedKey": "8a19cd6f74674df9017467f25aab02c8",
            "id": "_branches_grouped_cf_set",
            "name": "Custom Field Group for Branch",
            "notes": "",
            "createdDate": "2020-09-07T09:47:03+0000",
            "lastModifiedDate": "2020-09-07T09:47:03+0000",
            "indexInList": 3,
            "type": "BRANCH_INFO",
            "usage": "GROUPED"
          },
          "indexInList": 1,
          "state": "NORMAL",
          "customFieldSelectionOptions": [],
          "viewRights": {
            "encodedKey": "8a19cd6f74674df901746800bdb10309",
            "isAccessibleByAllUsers": true,
            "roles": []
          },
          "editRights": {
            "encodedKey": "8a19cd6f74674df901746800bdb1030a",
            "isAccessibleByAllUsers": true,
            "roles": []
          },
          "unique": false,
          "values": [],
          "amounts": {}
        },
        "value": "500",
        "indexInList": -1,
        "customFieldID": "cf_group_field_2",
        "customFieldSetGroupIndex": 1
      }
    ]
  },
  {
    "encodedKey": "8a193c26722b51b701722d779e7122df",
    "id": "2",
    "creationDate": "2020-05-19T15:05:23+0000",
    "lastModifiedDate": "2020-10-08T09:21:51+0000",
    "name": "Matola City",
    "state": "ACTIVE",
    "phoneNumber": "+7534987676",
    "emailAddress": "matola@BofAlg.es",
    "notes": "Is currently under construction to add an extra room that can be used for the meetings.<p></p>Have <b>six new computers</b> for their staff.",
    "branchHolidays": [
      {
        "encodedKey": "8a19df6972b787fc0172b8c50bdb0ba1",
        "keyId": 13,
        "name": "joe matola only day",
        "dayOfMonth": 26,
        "monthOfYear": 8,
        "year": 2020,
        "isAnnualyRecurring": true,
        "creationDate": "2020-06-15T16:17:19+0000"
      }
    ],
    "address": {
      "encodedKey": "8a19aa09750726e001750782ef6f017d",
      "parentKey": "8a193c26722b51b701722d779e7122df",
      "line1": "1 Bank Street",
      "line2": "Old Town",
      "city": "Matola City",
      "region": "Matola",
      "postcode": "10775",
      "country": "Bankistan",
      "indexInList": -1
    },
    "customFieldValues": []
  }
]

200 : ok
an array of branches with basic details

[
  {
    "encodedKey": "402832b43809601c01380963908b0009",
    "id": "2",
    "creationDate": "2012-06-20T12:15:16+0200",
    "lastModifiedDate": "2012-06-20T12:15:16+0200",
    "name": "Matola City"
  },
  {
    "encodedKey": "402832b43809601c01380963907c0008",
    "id": "demoBranchId",
    "creationDate": "2012-06-20T12:15:16+0200",
    "lastModifiedDate": "2012-06-20T12:15:16+0200",
    "name": "Maputo Downtown"
  }
]

Responses

Response Schema

Status Code 200

Enumerated Values

Get Branch by ID

GET /branches/{branchId}

Get a branch by ID

Get a specifc branch by its encoded key or ID.

Parameters

Example Responses

200 : ok
Full Details for a single branch

{
  "encodedKey": "8a33ae49441c4fe101441c713b36000e",
  "id": "2",
  "creationDate": "2014-02-10T15:36:26+0000",
  "lastModifiedDate": "2014-02-17T11:18:42+0000",
  "name": "Matola City",
  "phoneNumber": "",
  "emailAddress": "",
  "branchHolidays": [
    {
      "encodedKey": "8a54e5b4443e9c9401443fae924b0008",
      "keyId": 31,
      "name": "branch_holiday",
      "dayOfMonth": 17,
      "monthOfYear": 2,
      "year": 2014,
      "isAnnualyRecurring": true
    }
  ],
  "address": {
    "encodedKey": "8a19aa09750726e001750782ef6f017d",
    "parentKey": "8a193c26722b51b701722d779e7122df",
    "line1": "1 Bank Street",
    "line2": "Old Town",
    "city": "Matola City",
    "region": "Matola",
    "postcode": "10775",
    "country": "Bankistan",
    "indexInList": -1
  },
  "customFieldValues": [
    {
      "encodedKey": "8a42711a4428c1f101442be406d20c24",
      "parentKey": "8a33ae49441c4fe101441c713b36000e",
      "customFieldKey": "8a33ae49441c4fe101441c7156c20358",
      "customField": {
        "encodedKey": "8a33ae49441c4fe101441c7156c20358",
        "id": "Clients_Branches",
        "name": "Clients",
        "type": "BRANCH_INFO",
        "dataType": "STRING",
        "valueLength": "SHORT",
        "isDefault": false,
        "isRequired": false,
        "customFieldSet": {
          "encodedKey": "8a33ae49441c4fe101441c71568f034c",
          "name": "Branch Organization",
          "createdDate": "2014-02-10T15:36:33+0000",
          "indexInList": 0,
          "type": "BRANCH_INFO"
        },
        "indexInList": -1,
        "state": "NORMAL"
      },
      "value": "dadsds",
      "indexInList": -1
    },
    {
      "encodedKey": "8a54e5b4443e9c9401443f91c7a20003",
      "parentKey": "8a33ae49441c4fe101441c713b36000e",
      "customFieldKey": "8a33ae49441c4fe101441c7156c5035a",
      "customField": {
        "encodedKey": "8a33ae49441c4fe101441c7156c5035a",
        "id": "Organization_Staff_Branches",
        "name": "Organization Staff",
        "type": "BRANCH_INFO",
        "dataType": "NUMBER",
        "valueLength": "SHORT",
        "isDefault": false,
        "isRequired": false,
        "customFieldSet": {
          "encodedKey": "8a33ae49441c4fe101441c71568f034c",
          "name": "Branch Organization",
          "createdDate": "2014-02-10T15:36:33+0000",
          "indexInList": 0,
          "type": "BRANCH_INFO"
        },
        "indexInList": -1,
        "state": "NORMAL"
      },
      "value": "4",
      "indexInList": -1
    },
    {
      "encodedKey": "8a54e5b4443e9c9401443f91c7b90004",
      "parentKey": "8a33ae49441c4fe101441c713b36000e",
      "customFieldKey": "8a33ae49441c4fe101441c7156c30359",
      "customField": {
        "encodedKey": "8a33ae49441c4fe101441c7156c30359",
        "id": "Province_Branches",
        "name": "Province",
        "type": "BRANCH_INFO",
        "dataType": "SELECTION",
        "valueLength": "SHORT",
        "isDefault": false,
        "isRequired": false,
        "values": [
          "Catamarca",
          "Chaco",
          "Jujuy"
        ],
        "amounts": {
          "Jujuy": "10",
          "Chaco": "1",
          "Catamarca": "0"
        },
        "customFieldSet": {
          "encodedKey": "8a33ae49441c4fe101441c71569a034d",
          "name": "Province",
          "createdDate": "2014-02-10T15:36:33+0000",
          "indexInList": 1,
          "type": "BRANCH_INFO"
        },
        "indexInList": -1,
        "state": "NORMAL"
      },
      "value": "Catamarca",
      "amount": "0",
      "indexInList": -1
    },
    {
      "encodedKey": "8a54e5b4443e9c9401443f91c7b90005",
      "parentKey": "8a33ae49441c4fe101441c713b36000e",
      "customFieldKey": "8a33ae49441c4fe101441c7156c7035b",
      "customField": {
        "encodedKey": "8a33ae49441c4fe101441c7156c7035b",
        "id": "Outside_of_province_Branches",
        "name": "Outside of province",
        "type": "BRANCH_INFO",
        "dataType": "CHECKBOX",
        "valueLength": "SHORT",
        "isDefault": false,
        "isRequired": false,
        "customFieldSet": {
          "encodedKey": "8a33ae49441c4fe101441c71569a034d",
          "name": "Province",
          "createdDate": "2014-02-10T15:36:33+0000",
          "indexInList": 1,
          "type": "BRANCH_INFO"
        },
        "indexInList": -1,
        "state": "NORMAL"
      },
      "value": "FALSE",
      "indexInList": -1
    }
  ]
}

200 : ok
A single branch

{
  "encodedKey": "402832b43809601c01380963908b0009",
  "id": "2",
  "creationDate": "2012-06-20T12:15:16+0200",
  "lastModifiedDate": "2012-06-20T12:15:16+0200",
  "name": "Matola City"
}

Responses

Update Custom Info for Branch

PATCH /branches/{branchId}/custominformation

Update custom field values

Example Requests

Update a single custom field

{
  "customInformation": [
    {
      "customFieldID": "custom_field_2",
      "value": "3"
    }
  ]
}

Update field in a group

{
  "customInformation": [
    {
      "customFieldID": "cf_grouped_field",
      "value": "new value",
      "customFieldSetGroupIndex": "0"
    }
  ]
}

Update multiple custom fields

{
  "customInformation": [
    {
      "customFieldID": "cf_grouped_field_2",
      "value": "3",
      "customFieldSetGroupIndex": "0"
    },
    {
      "customFieldID": "field_3",
      "value": "divorced"
    }
  ]
}

Parameters

Example Responses

200 : OK
success response

{
  "returnCode": 0,
  "returnStatus": "SUCCESS"
}

Responses

Response Schema

Status Code 200

Get Custom Info for Branch

GET /branches/{branchId}/custominformation/{customFieldId}

Get a custom field for a Branch

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

Parameters

Example Responses

200 : OK
A custom field

[
  {
    "encodedKey": "8a19cd6f74674df9017467f25aab02c6",
    "parentKey": "8a193c26722b51b701722d779e7122de",
    "customFieldKey": "8a19cd6f74674df9017467ef8e6802af",
    "customField": {
      "encodedKey": "8a19cd6f74674df9017467ef8e6802af",
      "id": "cf_branch",
      "creationDate": "2020-09-07T09:42:33+0000",
      "lastModifiedDate": "2020-09-07T09:42:33+0000",
      "name": "Example Custom Field",
      "type": "BRANCH_INFO",
      "dataType": "CHECKBOX",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "an example custom field of the checkbox type",
      "customFieldSet": {
        "encodedKey": "8a19cd6f74674df9017467ef8e6802ae",
        "id": "_example_branch_custom_field_set",
        "name": "example branch custom field set",
        "notes": "example custom field set",
        "createdDate": "2020-09-07T09:41:50+0000",
        "lastModifiedDate": "2020-09-07T09:41:50+0000",
        "indexInList": 2,
        "type": "BRANCH_INFO",
        "usage": "SINGLE"
      },
      "indexInList": 0,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a19cd6f74674df9017467ef8e6802b0",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a19cd6f74674df9017467ef8e6802b1",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "TRUE",
    "indexInList": -1,
    "customFieldID": "cf_branch",
    "customFieldSetGroupIndex": -1
  }
]

404 : Not Found
not found

{
  "returnCode": 903,
  "returnStatus": "INVALID_CUSTOM_FIELD_ID"
}

Responses

Response Schema

Status Code 404

Update Custom Field for Branch

PATCH /branches/{branchId}/custominformation/{customFieldId}

Update a custom field for a Branch

Update a custom field value for a branch custom field

Example Requests

A new value for a custom field

{
  "value": "New value for custom field"
}

Parameters

Example Responses

200 : OK
Success Response

{
  "returnCode": 0,
  "returnStatus": "string"
}

400 : Bad Request
field is part of a group

{
  "returnCode": 916,
  "returnStatus": "INVALID_CUSTOM_FIELD_GROUP_INDEX",
  "errorSource": "cf_group_field_2"
}

404 : Not Found
not found

{
  "returnCode": 903,
  "returnStatus": "INVALID_CUSTOM_FIELD_ID"
}

Responses

Response Schema

Status Code 200

Status Code 400

Status Code 404

Delete Custom Info for Branch

DELETE /branches/{branchId}/custominformation/{customFieldId}

Delete a single custom field

Parameters

Example Responses

200 : OK
success response

{
  "returnCode": 0,
  "returnStatus": "SUCCESS"
}

400 : Bad Request
field is part of a group

{
  "returnCode": 916,
  "returnStatus": "INVALID_CUSTOM_FIELD_GROUP_INDEX",
  "errorSource": "cf_group_field_2"
}

404 : Not Found
not found

{
  "returnCode": 903,
  "returnStatus": "INVALID_CUSTOM_FIELD_ID"
}

Responses

Response Schema

Status Code 200

Status Code 400

Status Code 404

Update Custom Info (grouped) for Branch

PATCH /branches/{branchId}/custominformation/{customFieldId}/{customFieldGroupSetIndex}

Update grouped custom field

Update custom field which is part of a group

Example requests

Provide a new value for a custom field

{
  "value": "Some updated information"
}

Parameters

Example Responses

200 : OK
success response

{
  "returnCode": 0,
  "returnStatus": "SUCCESS"
}

400 : Bad Request
wrong group index provided

{
  "returnCode": 916,
  "returnStatus": "INVALID_CUSTOM_FIELD_GROUP_INDEX",
  "errorSource": "cf_group_field_2"
}

404 : Not Found
field not found

{
  "returnCode": 903,
  "returnStatus": "INVALID_CUSTOM_FIELD_ID"
}

Responses

Response Schema

Status Code 200

Status Code 400

Status Code 404

Delete Custom Info (grouped) for Branch

DELETE /branches/{branchId}/custominformation/{customFieldId}/{customFieldGroupSetIndex}

Delete grouped custom field

Delete a custom field which is part of a group

Parameters

Example Responses

200 : OK
Success Response

{
  "returnCode": 0,
  "returnStatus": "SUCCESS"
}

Responses

Response Schema

Status Code 200

Get Branch Comments

GET /branches/{branchId}/comments

Get all branch comments

get all comments for a branch

Parameters

Example Responses

200 : OK
an array of comments

[
  {
    "encodedKey": "8a19b7057471f4af017472dc0fd80470",
    "parentKey": "8a193c26722b51b701722d77c5e423b7",
    "userKey": "8a194075720ece2c017226fced6f005e",
    "creationDate": "2020-09-09T14:24:42+0000",
    "lastModifiedDate": "2020-09-09T14:24:42+0000",
    "text": "aanother afmaefomaef<div><br /></div><div><u>aefaefaf</u></div><div><u><br /></u></div><div><u>afaef</u></div>"
  },
  {
    "encodedKey": "8a193c26722b51b701722d77c8bf25ab",
    "parentKey": "8a193c26722b51b701722d77c5e423b7",
    "creationDate": "2020-05-19T15:05:24+0000",
    "lastModifiedDate": "2020-05-19T15:05:24+0000",
    "text": "Should suggest she apply for the agriculture loan given the nature of their business"
  }
]

400 : Bad Request
bad branch ID

{
  "returnCode": 149,
  "returnStatus": "INVALID_ID"
}

Responses

Response Schema

Status Code 200

Create Branch Comment

POST /branches/{branchId}/comments

Create a branch Comment

create new comment for a branch

Example Requests

A comment

{
  "comment": "A long text field containing the comment to post. this is a comment with \" \" all kinds of : \\ / non compliant characters & = which have \n been JSON escaped"
}

Parameters

Example Responses

200 : OK
a comment

{
  "encodedKey": "8a19c34574720f9e0174734a039f06e2",
  "parentKey": "8a193c26722b51b701722d77c5e423b7",
  "userKey": "8a194075720ece2c017226fced6f005e",
  "creationDate": "2020-09-09T14:39:36+0000",
  "lastModifiedDate": "2020-09-09T14:39:36+0000",
  "text": "this is a comment with \" \" all kinds of : \\ / non compliant stuff & = which has been JSON escaped"
}

400 : Bad Request
extra parameters in the request

{
  "returnCode": 27,
  "returnStatus": "PARAMETER_NOT_ALLOWED"
}

Responses

Response Schema

Status Code 400

Get Branch Documents

GET /branches/{branchId}/documents

Get documents for Branch

Get all documents for a given branch

Parameters

Example Responses

200 : ok
an array of documents

[
  {
    "encodedKey": "8a19c035747bf5b901747c5bfb04014b",
    "id": 51,
    "creationDate": "2020-09-11T08:52:48+0000",
    "lastModifiedDate": "2020-09-11T08:52:48+0000",
    "documentHolderKey": "8a193c26722b51b701722d779e7122df",
    "documentHolderType": "BRANCH",
    "name": "covid rules",
    "type": "png",
    "fileSize": 8258,
    "originalFilename": "Screenshot_2020-04-22_at_14.31.29.png",
    "location": "BRSIDSLFBOGAYZKUUKCOGGQEDOSEOD",
    "description": "some guidelines for bank employees regarding covid",
    "createdByUserKey": "8a194075720ece2c017226fced6f005e",
    "userName": "Adrian Doonan"
  },
  {
    "encodedKey": "8a19a3337476f2d00174775b6a3001ae",
    "id": 43,
    "creationDate": "2020-09-10T09:31:54+0000",
    "lastModifiedDate": "2020-09-10T09:31:54+0000",
    "documentHolderKey": "8a193c26722b51b701722d779e7122df",
    "documentHolderType": "BRANCH",
    "name": "bnranch doc",
    "type": "png",
    "fileSize": 32109,
    "originalFilename": "clients_duplicate_id.png",
    "location": "JRTBQGGVXFQRQRBDGBRWQCTXJNRWXP",
    "description": "branch doc desc",
    "createdByUserKey": "8a194075720ece2c017226fced6f005e",
    "userName": "Adrian Doonan"
  }
]

400 : Bad Request
bad branch ID

{
  "returnCode": 4,
  "returnStatus": "INVALID_PARAMETERS",
  "errorSource": "wrong owner id"
}

Responses

Response Schema

Status Code 200

Enumerated Values

Create Branch Document

POST /branches/{branchId}/documents

Attach new Document to a Branch

Attach a new document to a branch

Example Requests

a document to uplaod

{
  "document": {
    "documentHolderKey": "8a193c26722b51b701722d779e7122df",
    "documentHolderType": "BRANCH",
    "name": "some image",
    "type": "PNG",
    "description": "this is an image file"
  },
  "documentContent": "iVBORw0KGgoAAAANSUhEUgAAAnYAAAF0CAYAAACudHRvAAABQGlDQ1BJQ0MgUHJvZmlsZQAAKJFjYGASS=="
}

Parameters

Example Responses

201 : Created
uploaded document details

{
  "encodedKey": "8a19c035747bf5b901747c5bfb04014d",
  "id": 52,
  "creationDate": "2020-09-11T08:54:53+0000",
  "lastModifiedDate": "2020-09-11T08:54:53+0000",
  "documentHolderKey": "8a193c26722b51b701722d779e7122df",
  "documentHolderType": "BRANCH",
  "name": "some image",
  "type": "png",
  "fileSize": 32109,
  "originalFilename": "some_image.png",
  "location": "RCPOUIUHJFBYDRURQNNHMOGBEFIOQF",
  "description": "this is an image file",
  "createdByUserKey": "8a194075720ece2c017226fced6f005e"
}

400 : Bad Request
filetype provided does not match actual file type

{
  "returnCode": 973,
  "returnStatus": "INCONSISTENT_EXTENSION_WITH_FILE_CONTENT",
  "errorSource": "Invalid extension with file content"
}

Responses

Get Branch Document by ID

GET /branches/{branchId}/documents/{documentId}

Get a Branch Document

Get a specific document attached to a branch

Parameters

Example Responses

200 : OK
base64 encoded document

"iVBORw0KGgoAAAANSUhEUgAAAEAAAAA9CAYAAAAd1W/BAAAMY2lDQ1BJQ0MgUHJvZmlsZQAASImVVwdck0cbv3dkkrACEZAR9hJFZgAZIawIAjIFUQlJIGHEmBBE3NRSBesWUZxoVUTRagWkDkSssyhu6yiKqFRqsYoLle8yoNZ+4/c9v9+993+fe+7/jNzlvQNAr5Mvk+Wj+gAUSAvlCZGhrElp6SzSI4ABU0ADtsCTL1DIOPHxMQDKUP93eX0DIKr+qpuK65/j/1UMhSKFAAAkA=="

400 : Bad Request
bad Document ID

{
  "returnCode": 970,
  "returnStatus": "INVALID_DOCUMENT_ID"
}

Responses