API to validate UK bank account numbers, supporting authentication and rate limits
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Travis CI Software License GoDoc Coverage Status

Modulus checking API

This package is an API to validate UK bank account numbers, supporting authentication and rate limits. This package has been presented in a blog post where you can find instructions to deploy behind Nginx.

What is modulus checking?

Modulus checking is a procedure for validating sort code and account number combinations for UK bank accounts.


  • A working Go installation
  • A Redis server if you want to rate limit requests

Other packages used

For additional documentation, check out these packages I'm using:

Getting started

You can grab this package with the following command:

go get github.com/AntoineAugusti/moduluschecking-api

And then build it using the Makefile:

cd ${GOPATH%/}/src/github.com/AntoineAugusti/moduluschecking-api
make build
cp moduluschecking-api ${GOPATH%/}/bin/moduluschecking-api

Building the package using the Makefile will allow the /heartbeat and /version endpoints to echo the Git hash of the current build and the date of the current build.


From the -h flag:

Usage of ./moduluschecking-api:
  -a string
        address to listen (default ":8080")

API endpoint


Purpose: Check that a UK bank account number is valid.


Expected HTTP headers:

Key Value
Api-Key The value of the API key. The only supported value for now is foo.
Content-Type application/json; charset=UTF-8

JSON payload:




For a status code of 200:

HTTP header key Value
Api-Remaining The number of requests remaining. The current limit is 5 requests / second. Example: 3
Content-Type application/json; charset=UTF-8



Each error is given as a JSON response containing 2 keys (status and message), describing the source of the error. The Content-Type HTTP header is always set to application/json; charset=UTF-8.


  "message":"API rate exceeded. Too many requests."
HTTP status code status value message value
400 invalid_bank_account Expected a 6 digits sort code and an account number between 6 and 10 digits.
401 authorization_required Please provide a HTTP header called Api-Key
422 invalid_json Cannot decode the given JSON payload
429 rate_exceeded API rate exceeded. Too many requests.