Skip to main content

HTTP Verbs

Standard HTTP verbs are used to indicate the API request method.

VerbFunction
GETTo retrieve a resource or a collection of resources
POSTTo create a resource
PATCHTo modify an existing resource
PUTTo replace an existing resource
DELETETo delete a resource

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. For more information, see Creating a User - Access Rights in our User Guide.

note

To ensure the username and password cannot be intercepted, all requests must use HTTPS.

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.

Payloads​

Mambu API v1 has endpoints that usually accept and return only application/json. When making a POST, PUT, or PATCH request that sends data through a JSON body, you must set the Content-Type header to application/json. When making a POST request that sends data through query parameters, the Content-Type header must not be set.

Requests​

API requests (also known as API calls) 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:

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 contain either the JSON-formatted payload or an error response.

Error response​

An error response will consist of:

FieldTypeAvailabilityContent
errorCodenumberAlways presentA unique error code. For more information, see API Responses and Error Codes.
errorSourcestringSometimes presentA human-readable message capturing unsatisfied constraints.
errorReasonstringAlways presentA human-readable message stating the general category of the failure.
note

The contents of the errorSource and ErrorResponse fields are subject to change without backwards compatibility.

Sandbox​

The sandbox tenant (also known as sandbox environment) is independent from the production tenant, and any changes you make in the sandbox will not affect the data in your production tenant. For more information, see [Sandbox](/docs/ sandbox) in our User Guide.

To make requests to your tenant's sandbox, use the following base URL:

  • https://TENANT_NAME.sandbox.mambu.com/api/

The sandbox is generally one version ahead of the production tenant. As such, it may include changes that are currently in, or may soon be in, the production environment. For more information, see [Mambu Release Cycle](/docs/ mambu-release-cycle).

Sandbox management​

To manage your sandbox go to the Customer Service Portal. For more information and instructions, see [Customer Service Portal - Sandbox Management](/docs/ customer-service-portal#sandbox-management).

Pagination​

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

warning

When making a POST request that sends data through query parameters - as with Pagination - the Content-Type header must not be set.

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​

Some Mambu API v1 endpoints support two levels of detail for responses, basic details and full details. To retrieve a response in full details, you must set the fullDetails query parameter to true.

Basic details​

By default, Mambu API v1 will return basic details, this includes all first level elements of an object.

Full details​

Some endpoints can return full details, this includes everything from basic details as well as all custom field values, any address or contact information, and any other related objects.

Audit Trail and the User-Agent Header​

Error when User Agent header is not provided

{
  "errors": [
    {
      "errorCode": 4,
      "errorSource": "The user agent cannot be null when the Audit Trail feature is enabled",
      "errorReason": "INVALID_PARAMETERS"
    }
  ]
}

Audit trail tracks all activities performed in the Mambu Core Banking system via the UI or API v1 and v2. For more information, see Audit Trail in our User Guide.

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 error message The user agent cannot be null when the Audit Trail feature is enabled.

Note that if you are using a REST client like Postman or Curl, this header is probably provided automatically. However, if you generate a request to the API, you must provide it yourself.

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.

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.

warning

GET and POST requests using query parameters should always use url-encoding for parameter values to make sure any special characters are properly escaped and do not cause errors or loss of information.

The examples to the right, 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 example to the right 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"
    }
]
Using the Authorization header

You can alternatively supply 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 ':', ie dXNlcm5hbWU6cGFzc3dvcmQ= would be the result for username:password.