API Overview


The Modulr API platform lets developers manage and automate the flow of money by creating bank accounts with Sort Codes and making bank transfers.

The API is based on REST, and uses standard REST features like resource-based endpoints, HTTP verbs, standard responses and authentication.

You can use the Modulr API to:

  • Automate payments to multiple customers via bank transfers (Faster Payments)
  • Create unique Collection accounts to streamline incoming payments from creditors and receive notifications of incoming funds
  • Manage funds on behalf of 3rd parties

API Overview

Base URLs

The base URLs for the Modulr API sandbox environment are:

https://api-sandbox.modulrfinance.com/api-sandbox/ for SANDBOX

You can register on this portal to access the API catalogue and get test a API key.

You will be provided with the Production URL directly during sign up.

The API should be accessed over HTTPS only. Access to the Modulr API is restricted by IP address in Production - your IP addresses will be allow listed before you can start using service.


The API is protected with HMAC authentication, which requires you to calculate a signature based on certain message contents and include that in the Authorization header when making requests.

This value will be unique per request and uses a _keyid (token) and a _hmacsecret value that will both be provided to you. Different keys will be needed for sandbox and live. Instructions on how to calculate the hmac value are below.

Please store keys and secrets securely (particularly any LIVE tokens) as they authenticate all requests as being approved from your organisation. Sandbox environment keys may be time limited to a month for evaluation purposes, please contact us if you require an extension.

HMAC Signatures / Authorization header calculation

HMAC Signing is an access token method that adds another level of security by also sending a signature that identifies the request temporally to ensure that the request is from the requesting user, using a secret key that is never broadcast over the wire. HMAC signing implemented is based on the latest draft of the HMAC request signing standard.

The required steps and a worked example are provided below, please contact us if you require any further assistance.

Sample code is available here.

  1. Set the HTTP “Date” header. The date format must be exactly as per the HTTP-date header specifications - RFC 7231

    example header
       Date: Mon, 25 Jul 2016 16:36:07 GMT
  2. Set a header with label x-mod-nonce to a unique value per request (see below regarding nonces)

    example header
       x-mod-nonce: 28154b2-9c62b93cc22a-24c9e2-5536d7d
  3. Create the signature string by concatenating the two headers above separated by a single newline character (note \n and not \r\n).

    The header labels should be lowercase within the signature string.

    signatureString := strings.ToLower("Date") + ": " + HTTP-date + "\n"
    signatureString += strings.ToLower("x-mod-nonce") + ": " + nonce
    example signature string
       date: Mon, 25 Jul 2016 16:36:07 GMT\nx-mod-nonce: 28154b2-9c62b93cc22a-24c9e2-5536d7d
  4. For a given key of 57502612d1bb2c0001000025fd53850cd9a94861507a5f7cca236882 and hmac secret of NzAwZmIwMGQ0YTJiNDhkMzZjYzc3YjQ5OGQyYWMzOTI= calculate the hmac-SHA1 signature of the signature string.

    Convert the result to a url encoded base64 string.

    You should get a value of:

    hex = 58132bfd8761cac6e6888124753adfda13fb49f0
    url encoded base 64 = WBMr%2FYdhysbmiIEkdTrf2hP7SfA%3D
  5. Set the Authorization header result with the below format

    example header
       Authorization: Signature keyId="57502612d1bb2c0001000025fd53850cd9a94861507a5f7cca236882",algorithm="hmac-sha1",headers="date x-mod-nonce",signature="WBMr%2FYdhysbmiIEkdTrf2hP7SfA%3D"

Accurate time and clock skew

The HMAC calculation above uses a date/time value and also implements the recommended clock-skew from the HMAC specification to prevent against replay attacks. It is therefore essential that the sending system has an accurate time (e.g. synchronised with NTP), any significant time error may cause the request to be rejected.

Nonce value

The HMAC calculation above uses a nonce value. This value should be set and be unique per request that you send to our system. This is used in conjunction with the datetime to prevent replay attacks and detect duplicate messages. Suitable nonce examples may be: GUID/UUID, timestamp with a random element to allow for concurrent messages, sequential id’s etc. The only time a nonce should be re-used is if you do not receive a response from our system for an API call (as opposed to an error) and wish to re-try the same message, in which case you should use the same nonce as this will detect whether we have received and processed it.

Idempotent Requests

The API supports idempotency for safely retrying non-idempotent requests without accidentally performing the same operation twice. For example, if a POST request to create a payment fails due to a network connection error, you can retry the request with the same x-mod-nonce to guarantee that only a single payment is created.

To retry a POST request idempotently you can:

  • Reuse the same x-mod-nonce as the original POST request and
  • Set the header x-mod-retry = true

This will send back the same response for requests made with the same x-mod-nonce for 24 hours. You cannot use the same nonce with different request parameters.

Rate Limiting & Quotas

All endpoints are rate limited (X requests in X seconds), and each API key has a quota.

You can check the returned HTTP headers of any API request to see your current quota status, for example:

x-ratelimit-limit: 30000
x-ratelimit-remaining: 989
x-ratelimit-reset: 1480359249

x-ratelimit-reset uses Unix time to indicate when the quota is due to reset.

Exceeding the quota results in:

403 {"error": "Quota exceeded"}
429 {"error": "Rate limit exceeded"}

Backwards compatibility

The following changes are considered backwards compatible, and should be handled:

  • Adding new API endpoints
  • Adding new properties to the responses from existing API endpoints
  • Reordering properties returned from existing API endpoints
  • Adding optional request parameters to existing API endpoints
  • Altering the format or length of IDs
  • Altering the message attributes returned by validation failures / other errors
  • Sending webhooks for new event types

MIME Types

All requests and responses are JSON-formatted. You must pass the standard JSON MIME type (application/json). Other content types will return a 500 error - Content type not supported”

Response Status Codes

The API uses the following response status codes:

Status Code Description
200 OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.
201 Created - The resource was created successfully. The response may have information about the newly created resource.
400 Bad Request - This is likely caused by validation errors, response body will provide further information. the client should make changes and resubmit,
403 Forbidden - The client is not allowed to access the resource. Please check your access token is valid and has not expired/ been revoked
404 Not Found - The requested resource doesn’t exist. Please check documentation and the request.
405 Method Not Allowed - HTTP method used to access this resource is incorrect, please check documentation
500 Internal Server Error - Response body may contain further information. You may need to contact Modulr administrator

Please ensure that your application is able to process additional / new json fields in the body of responses without erroring. Addition of fields in the response will not be considered a breaking change by us.


Errors on the Modulr API will return a 4XX or a 5XX HTTP response code.

Additional information about the error will be returned in the response body, in the format:

		"field": "id",
		"code": "NOTFOUND",
		"message": "Customer not found for id: C0200002"


Responses for list endpoints (Accounts, Transactions, Beneficiaries) are paginated by default.


The following options are available on all cursor-paginated endpoints:

  • Page - Page to fetch (0-indexed)
  • Size - number of elements to return. Maximum value is 500


Paginated results are always returned in an array, and include the following meta data:

	"size": 15,
	"totalSize": 189,
	"page": 1,
	"totalPages": 13

Time zones

All timestamps are formatted as ISO8601 with timezone information. For API calls that allow for a timestamp to be specified, we use that exact timestamp. These timestamps look something likeĀ 2016-06-01T12:00:00.111Z. All times should be sent in UTC time zone.

For endpoints that require dates, we expect a date string of the formatYYYY-MM-DD, where an example would look likeĀ 2016-06-01.