ClearBank

API Requests

Overview

For GET requests, you can use one or more query parameters. In the response we will return a HTTP status code. Some endpoints return JSON bodies that include HAL (Hypertext Application Language) links.

Query Parameters

For most of our GET requests, one or more query parameters in the request URL can be used to specify the number of returned results and the number of pages returned.

ParameterTypeDescription
pageNumberintThe page number to control returned results into manageable sets. Default if not supplied: 1 pageNumber=1
pageSizeintThe page size to control returned results into manageable sets. Default if not supplied: 50 pageSize=50

HTTP Status Codes

ClearBank® requests return a HTTP status code to indicate the success or failure of a request. For successful requests, we return a HTTP 2XX status code. For failed requests, we return a HTTP 4XX or 5XX status code. Some endpoints return JSON response bodies that include errors and additional properties.

Status CodeDescription
200Success!
201Success!
202Request received successfully and is being processed
400Bad request. Something went wrong with the request. The response should include the reason why the request has failed
403Forbidden. Your API token does not have permissions to perform the request
404Not found. The resource you are looking for cannot be found
409Conflict. A request conflict with the current state of the server
429Too many requests. You have sent too many requests in a given time ("rate limiting")
500Internal server error
503Server error. Service unavailable

5xx status codes

If you receive a 5xx error code, you should retry your request as these are service errors. A request that returns these errors may, in exceptional circumstances, result in being processed regardless. Following which, you will receive a notification (webhook) delivered to you as expected.

To avoid any duplication, always retry all such requests with exactly the same request Id header and payload. If the initial request is successful, the retry request will trigger a notification (HTTP response or webhook) to confirm that it has not been processed as it was identified as a duplicate.

Example of a response containing detailed errors

{
  "errors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

HAL Links

We use HAL (Hypertext Application Language) to hyperlink between resources in our API.

Each HAL hyperlink contains:

ParameterTypeRequiredDescription
namestringRequiredThe named link type
hrefstringRequiredURI to be used
templatedbooleanSpecified as true if href is a URI template, i.e. with parameters. Otherwise, this property is absent or set to false

Example HAL Links

{
    "accounts": [
        {
            "id": "9140d28b-58d4-4e14-a5fe-43a655c82162",
            "name": "Gen Seg Acc Wsale - TradingBankEnd2End",
            "type": "CACC",
            "currency": [
                "GBP"
            ],
            "balances": [
                {
                    "name": "Gen Seg Acc Wsale - TradingBankEnd2End",
                    "amount": 2000000.00,
                    "currency": "GBP",
                    "status": "VALU"
                }
            ],
            "iban": "GB90CLRB04190000001107",
            "bban": "CLRB04190000001107"
        },
        {
            "id": "9b3dd95c-92a0-4c22-8314-da97906f4a2b",
            "name": "Mandated Minimum Balance Account",
            "type": "CACC",
            "currency": [
                "GBP"
            ],
            "balances": [
                {
                    "name": "Mandated Minimum Balance Account",
                    "amount": 2000000.00,
                    "currency": "GBP",
                    "status": "VALU"
                }
            ],
            "iban": "GB57CLRB04190000001119",
            "bban": "CLRB04190000001119"
        },
        {
            "id": "0392ffce-fd15-47a6-824f-708e0bee007b",
            "name": "Operating Account",
            "type": "CACC",
            "currency": [
                "GBP"
            ],
            "balances": [
                {
                    "name": "Operating Account",
                    "amount": 1999992.00,
                    "currency": "GBP",
                    "status": "VALU"
                }
            ],
            "iban": "GB95CLRB04190000001114",
            "bban": "CLRB04190000001114"
        }
    ],
    "halLinks": [
        {
            "name": "self",
            "href": "https://institution-sim.clearbank.co.uk/v1/Accounts",
            "templated": false
        },
        {
            "name": "Account",
            "href": "https://institution-sim.clearbank.co.uk/v1/Accounts/{accountId}",
            "templated": true
        },
        {
            "name": "Transactions",
            "href": "https://blue-institution-sim.clearbank.co.uk/v1/Accounts/{accountId}/Transactions",
            "templated": true
        },
        {
            "name": "Mandates",
            "href": "https://blue-institution-sim.clearbank.co.uk/v1/Accounts/{accountId}/Mandates",
            "templated": true
        }
    ]
}