Hub Accounts

Hub Accounts are FSCS protected bank accounts held with ClearBank that enable innovative financial products. Use cases for Hub Accounts typically involve making payments to and from a defined set of associated accounts.

To ensure regulatory compliance, Hub Accounts may be subject to one or more of the following constraints:

Payments may only be made for specific purposes.
Payments may only be made to and from certain designated bank accounts.
Payment frequency may be restricted.

Exact details will be agreed with your institution directly.

Hub Accounts are available by prior agreement with ClearBank; if you're interested in using these, please speak with your Client Director.

Hub Accounts can be created using the POST /accounts/sterling/v1/hub-accounts endpoint. Before creating a Hub Account, you'll need the following information:

The account-holding customer's details.
Your sort code, provided to you by ClearBank.
A productId, also provided to you by ClearBank.
Optionally, if your Hub Accounts are interest bearing, an interestConfigurationId.

Account holding customer
Each Hub Account must be held by a retail customer or business customer. The holder of a Hub Account is entitled to its funds. Refer to our retail customers page, or contact your Client Director for guidance on creating business customers.

Once you've created a retail or business customer, take note of their customerId and legal name - you'll need these to associate the customer with their new Hub Account.

Sort code
A sort code will have been assigned to you as part of your onboarding process.

Product identity
The productId you should use will be provided to you as part of onboarding. This ID determines how your Hub Account behaves.

Interest payments (optional)
If your Hub Accounts are configured to accrue interest, you can subscribe to the Interest Paid webhook to be notified when interest is paid into the account.

Interest configuration (optional)
Hub Accounts may be interest bearing. This will have been agreed between your institution and ClearBank. If your Hub Accounts are interest bearing, you can set up their interest configuration profile. Once created, the profile's interestConfigurationId may be reused across subsequent Hub Accounts to refer to the same configuration profile.

Create a Hub Account

post/accounts/sterling/v1/hub-accounts

Use this endpoint to create a new hub account.

Parameters

Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Request Payload (application/json)

ownerName string, Required
The name used to identify the legal owner of the hub account.
Minimum length
0
Maximum length
140
Pattern
^[^\|_\[\]<>^`~\\$]*$
sortCode string, Required
The sort code that the account should be created under. Should not include hyphens.
Pattern
^\d{6}$
productId string, Required
The product identifier of the account. It is used to determine the behaviour of the account.
Pattern
^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
customers array, Required
The customers who hold the account.
interestConfigurationId string
The unique identifier of the interest configuration. This determines the how interest is accrued on the account.
Pattern
^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

request

{
  "ownerName": "John Smith",
  "sortCode": "010203",
  "productId": "74b00ccf-c4ad-470c-ac29-ce57cb658527",
  "customers": [
    {
      "customerId": "5b9beca1-d9a8-40d0-bd65-0747d5959cff"
    }
  ],
  "interestConfigurationId": "d20b2c84-6c9e-4ebb-84ad-be9d5be97188"
}

Code copied

Response (application/json)

201 Success
400 Bad Request
404 Not Found
422 Client Error

Success

{
  "account": {
    "accountId": "232d0a3c-0933-4894-9fbc-230cf183c7ed",
    "productId": "b4f9853e-40c0-4203-97e0-7a42075d6dda",
    "customers": [
      {
        "customerId": "5b9beca1-d9a8-40d0-bd65-0747d5959cff"
      }
    ],
    "interestConfigurationId": "24df1e52-24d9-4bda-86af-c81a7d1932b1",
    "accountName": "Hub Account",
    "ownerName": "John Smith",
    "iban": "GB12CLBK01020312345678",
    "bban": "CLBK01020312345678",
    "createdDateTime": "2024-01-01T12:34:56.789+00:00"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Client Error

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Associated Webhooks

Account Created webhook

This webhook confirms the account has been created.

Request body

{
    "Type":"AccountCreated",
    "Version":1,
    "Payload": {...},
    "Nonce":
}

Payload

Element
`AccountId`	Account identifier used to uniquely identify the account. Type: `string` Format: `GUID`
`AccountName`	Name of the account. Type: `string` Max. length: `128`
`AccountHolderLabel`	The account description. Type: `string` Max. length: `100`
`AccountIdentifiers`	Account identifier details. Type: `object` `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30`
`TimestampCreated`	The date and time the account was created. Type: `string` Time Zone: `UTC` Format: `DateTime`
`AccountType`	Type of account. Type: `string` Examples: `CurrentAccount`, `DepositAccount`, `ControlAccount`, `SegregatedClientAccount`, `InstitutionAccount`
`LegalOwnerType`	The legal owner type of the created account. This field will only be populated when creating a cash ISA, hub, or savings account. Type: `string` Examples: `Personal`, `Business`
`RelationshipType`	The relationship type of the created account. This field will only be populated when creating a cash ISA, hub, or savings account. Type: `string` Examples: `Single`, `Joint`
`Customers`	Information about the customer(s). Type: `array` Max. Length: `5` `CustomerId`: The ID associated with the customer. Type: `guid` Max. length: `36` Min. length: `36` Pattern: `^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$`
`Nonce`	Cryptographically secure number generated by ClearBank for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example account created webhook request body

{
    "Type":"AccountCreated",
    "Version":1,
    "Payload":{
        "AccountId":"56de3483-a569-42eb-90cc-acf59661356f",
        "AccountName":"JOHN DOE",
        "AccountHolderLabel":"JOHN DOE",
        "AccountIdentifiers":{
            "IBAN":"GB00CUBK11223312345678",
            "BBAN":"CUBK11223312345678"
        },
        "TimestampCreated":"2018-07-19T13:31:30.8789344Z",
        "AccountType":"CurrentAccount",
        "LegalOwnerType":"Personal",
        "RelationshipType":"Single",
        "Customers":
        {
            "CustomerId":"b7e2c8a1-4c2d-4e2a-9e8b-2f6e7b1d9c3a"
        }
    },
    "Nonce":1082937278
}

Example webhook response

{
    "Nonce": 1082937278
}

Other bank accounts can be linked to a Hub Account as an associated account or a nominated account. Funds can only transferred between a Hub Account and its associated or nominated accounts.

Nominated account
A nominated account is a single account designated for funding and defunding a Hub Account.

Nominated accounts do not need to be ClearBank provided: they can be from another external provider.
The account holder for the nominated account and the Hub Account must be the same.
When a Hub Account is closed, any unpaid interest is redirected to its nominated account.

To set or replace the nominated account for a Hub Account, you can use the POST /v1/accounts/{accountId}/related-accounts (preferred), or the PUT /v1/accounts/{accountId}/nominated-account endpoint.

You can make payments from a Hub Account to its nominated account via Faster Payments or CHAPS; to receive updates about FPS transactions for a Hub Account, you can subscribe to the Transaction Settled webhook.

Associated accounts
Associated accounts are one or several accounts defined to fulfil a specific role in relation to a Hub Account. The function of an associated account will vary depending on your specific use case:

An associated account does not need to be ClearBank provided: they can be from another external provider.
The number of associated accounts you may link to a Hub Account is limited, and will depend on your arrangement with ClearBank.
Hub Account funding to and from an associated account may or may not be allowed. This depends on your arrangement with ClearBank.

Associated accounts can be added to a Hub Account using the POST /v1/accounts/{accountId}/related-accounts endpoint; removed using the DELETE /v1/accounts/{accountId}/related-accounts/{iban} endpoint; and retrieved using the GET /v1/accounts/{accountId}/related-accounts endpoint.

If you need to update the account holder of an associated account, you can use the PATCH /v1/accounts/{accountId}/related-accounts/{iban} endpoint.

Example use case
Hub Accounts could be used to temporarily hold funds between a customer and a vendor.

For example, a Hub Account can be funded from a customer's nominated external account. Funds may then be held in the Hub Account for a defined period before being released to a third‑party vendor for the delivery of services.

Add an associated or nominated account

post/v1/accounts/{accountId}/related-accounts

You can call this endpoint to add a new nominated or associated account to a Hub Account.

Parameters

accountId string, path, Required
The unique identifier for the account.
Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Request Payload (application/json)

relatedAccountType string, Required
The type of related account you're creating ('Nominated' or 'Associated').
Minimum length
1
identifier string, Required
The associated or nominated account's identifier (You can use an IBAN, BBAN or SCAN).
Minimum length
0
Maximum length
50
identifierKind string, Required
The type of identifier being used. Possible values are: 'IBAN', 'BBAN' or 'SCAN'.
Minimum length
1
Maximum length
4
ownerName string, Required
The name of the account owner. If creating a nominated account, this should be the same as Hub Account's.
Minimum length
0
Maximum length
140
Pattern
^[0-9a-zA-Z/-?:().,’'+ !#%&\*=^_`\{\|\}~"";<>@\[\\]]+

request

{
  "relatedAccountType": "Nominated",
  "identifier": "GB26CBUK40231512245674",
  "identifierKind": "IBAN",
  "ownerName": "John Smith"
}

Code copied

Response (application/json)

201 Created
400 Bad Request
404 Not Found
409 Conflict
422 Client Error

Created

{
  "account": {
    "accountId": "232d0a3c-0933-4894-9fbc-230cf183c7ed",
    "relatedAccount": {
      "relatedAccountType": "Nominated",
      "ownerName": "John Smith",
      "identifiers": {
        "iban": "GB26CBUK40231512245674",
        "bban": "CBUK40231512245674",
        "scan": "40231512245674"
      },
      "createdDateTime": "2019-08-24T14:15:22Z",
      "modifiedDateTime": "2019-08-24T14:15:22Z"
    }
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Not Found

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Conflict

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Client Error

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Retrieve associated and nominated accounts

get/v1/accounts/{accountId}/related-accounts

You can call this endpoint to retrieve the details of all nominated and associated accounts for a given Hub Account.

Parameters

accountId string, path, Required
The unique identifier for the account.
Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.

Response (application/json)

200 Success
400 Bad Request
404 Not Found

Success

{
  "account": {
    "accountId": "232d0a3c-0933-4894-9fbc-230cf183c7ed",
    "relatedAccounts": [
      {
        "relatedAccountType": "Nominated",
        "ownerName": "John Smith",
        "identifiers": {
          "iban": "GB26CBUK40231512245674",
          "bban": "CBUK40231512245674",
          "scan": "40231512245674"
        },
        "createdDateTime": "2019-08-24T14:15:22Z",
        "modifiedDateTime": "2019-08-24T14:15:22Z"
      }
    ]
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Amend an associated or nominated account

patch/v1/accounts/{accountId}/related-accounts/{iban}

You can call this endpoint to update the name of the account holder for an existing nominated or associated account.

Parameters

accountId string, path, Required
The unique identifier for the Hub Account.
iban string, path, Required
The IBAN of the linked nominated or associated account.
Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Request Payload (application/json)

ownerName string, Required
The new legal name of the account owner.
Minimum length
0
Maximum length
140

request

{
  "ownerName": "John Smith"
}

Code copied

Response (application/json)

200 Success
400 Bad Request
404 Not Found
422 Client Error

Success

{
  "accountId": "232d0a3c-0933-4894-9fbc-230cf183c7ed",
  "relatedAccounts": [
    {
      "relatedAccountType": "Nominated",
      "ownerName": "John Smith",
      "identifiers": {
        "iban": "GB26CBUK40231512245674",
        "bban": "CBUK40231512245674",
        "scan": "40231512245674"
      },
      "createdDateTime": "2019-08-24T14:15:22Z",
      "modifiedDateTime": "2019-08-24T14:15:22Z"
    }
  ]
}

Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Not Found

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Client Error

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Remove an associated or nominated account

delete/v1/accounts/{accountId}/related-accounts/{iban}

You can call this endpoint to remove a nominated or associated account from a Hub Account.

Parameters

accountId string, path, Required
The unique identifier of the Hub Account.
iban string, path, Required
The IBAN identifier associated with the (nominated or associated) related account.
Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Response (application/json)

204 No Content
400 Bad Request
404 Not Found

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Not Found

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Set a nominated account

put/v1/accounts/{accountId}/nominated-account

This endpoint is used to set a nominated account.

Parameters

accountId string, path, Required
The unique identifier for the real account associated with the nominated account. This can be retrieved from GET /v3/Accounts.
Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Request Payload (application/json)

identifier string, Required
The identifier for the nominated account. IBAN is the preferred format.
Minimum length
0
Maximum length
50
identifierKind string, Required
The type of identifier for the nominated account. Supported values are 'IBAN', 'BBAN' and 'SCAN' (Sort Code and Account Number).
ownerName string, Required
The name used to identify the legal owner of the nominated account.
Minimum length
1
Maximum length
140
Pattern
^[0-9a-zA-Z\/\-\?:\.,’'\+ !#$%&\*=^_`\{\|\}~"";<>@\[\\\]]+$

request

{
  "identifier": "GB29NWBK60161331926819 (IBAN), NWBK60161331926819 (BBAN) or 60161331926819 (SCAN)",
  "identifierKind": "IBAN",
  "ownerName": "John Smith"
}

Code copied

Response (application/json)

200 OK
400 Bad Request
404 Not Found

OK

{
  "nominatedAccount": {
    "identifier": "GB12CLBK01020312345678",
    "identifierKind": "IBAN",
    "ownerName": "John Smith"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Get a nominated account

get/v1/accounts/{accountId}/nominated-account

This endpoint is used to get the details of a nominated account.

Parameters

accountId string, path, Required
The unique identifier for the real account associated with the nominated account. This can be retrieved from GET /v3/Accounts.
Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.

Response (application/json)

200 OK
404 Not Found

OK

{
  "nominatedAccount": {
    "accountId": "01234567-89ab-cdef-0123-456789abcdef",
    "identifier": "GB12CLBK01020312345678",
    "identifierKind": "IBAN",
    "ownerName": "John Smith",
    "createdDateTime": "2024-05-01T00:00:00+01:00",
    "modifiedDateTime": "2024-05-01T00:00:00+01:00"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

This webhook confirms that interest has been paid on the posting day for both the end customer and the embedded banking customer. It will also trigger for the outstanding accrual payment for account closures. A Transaction Settled webhook will be received at the same time and these can be matched using the TransactionID field in both.

Note that the DestinationAccountID refers to the hub account, savings account, or cash ISA account holding the balance that the interest is calculated against.

Request body

{
    "Type":"InterestPaid",
    "Version":1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`TransactionId`	Required Transaction identifier used to uniquely identify the transaction. Type: `string` Format: `GUID` Min. Length: `1`
`EndToEndTransactionID`	Optional Unique internal identifier defined by ClearBank for each payment. Type: `null`, `string` Format: `GUID` Min. Length: `0` Max. Length: `35`
`Amount`	Required Amount of interest paid. Type: `number` Format: `decimal`
`CurrencyCode`	Optional Three-letter ISO currency code for the currency of the interest payment. Type: `null`, `string` Min. Length: `3` Max. Length: `4`
`DebitCreditCode`	Optional Indicates whether the transaction is a debit or credit. Type: `null`, `string` Options:`Credit`, `Debit`
`Timestamp`	Required Date and time of the interest payment. Time in UTC. Format: `date-time` Min. Length: `1`
`Reference`	Required Transaction reference of the interest payment. Max. Length: `140`
`DestinationAccountId`	Required Destination account ID for the interest payment. For Embedded Banking Partners, this is the account your interest is paid into (not the account that accrued the interest). Type: `string` Format: `GUID` Min. Length: `1`
`AccrualPeriod`	Optional Start and end date of the interest accrual period. This date is local to the region where the account is held. Type: `null`, `object` `Start` Start date of the accrual period. Type: `string` Format: `date` Min. Length: `1` `End` End date of the accrual period. Type: `string` Format: `date` Min. Length: `1`

Example Interest Paid webhook request body

{ 
    "Type": "InterestPaid", 
    "Version": 1, 
    "Payload": { 
        "TransactionId": "13124f38-c5ea-4f99-a597-ab92b610629a", 
        "EndToEndTransactionId": "13124f38c5ea4f99a597ab92b610629a",
        "Amount": 20.01, 
        "CurrencyCode": "GBP", 
        "DebitCreditCode": "Credit", 
        "Timestamp": "2026-01-31T11:41:07.334209Z", 
        "Reference": "Interest payable for period 31st December 2025 to 31st January 2026", 
        "DestinationAccountId": "a23e77aa-44c2-45fb-24a3-6c6d3f54b894" 
        "AccrualPeriod": {
            "Start": "2025-12-31",
            "End": "2026-01-31"
        }
    }, 
    "Nonce": 1289947472 
}

Example webhook response

{
    "Nonce": 1289947472
}

You can retrieve information on all Hub Accounts by using the GET /v3/accounts endpoint and filtering for Hub Accounts.
To retrieve information about a specific Hub Account, you can use the GET /v3/Accounts/{accountId} endpoint.

To make any updates to an existing Hub Account, you can use the PATCH /v1/accounts/{accountId} endpoint.

Get all real accounts, including Hub Accounts

get/v3/Accounts

Gets all accounts associated with your institution.

All accounts are returned except those which have been disabled or where the account is a virtual account.

Parameters

pageNumber integer, query
The page number to control returned results into manageable sets. Default if not supplied: 1.
pageSize integer, query
The page size to control returned results into manageable sets. Default if not supplied: 50.
Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.

Response (application/json)

200 OK
400 Bad Request

OK

{
  "accounts": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Sample Account Type Name",
      "label": "John Smith",
      "type": "CACC",
      "currency": "GBP",
      "balances": [
        {
          "name": "Current Account",
          "amount": 2310.55,
          "currency": "GBP",
          "status": "VALU",
          "balanceLastUpdatedAt": "2025-04-19T10:02:00.964Z"
        }
      ],
      "minimumBalance": {
        "name": "Current Account",
        "amount": -200,
        "currency": "GBP",
        "status": "VALU"
      },
      "productType": "Segregated",
      "accountSubType": "SafeguardedPooled",
      "legalOwnerType": "Personal",
      "relationshipType": "Single",
      "status": "Enabled",
      "statusReason": "Other",
      "timestampCreated": "2025-02-19T11:32:10.934Z",
      "timestampModified": "2025-05-25T18:27:12.524Z",
      "iban": "GB12CLBK01020312345678",
      "bban": "CLBK01020312345678",
      "upic": "string",
      "cuid": "string"
    }
  ],
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Get information for a Hub Account

get/v3/Accounts/{accountId}

Gets a detailed view of an account.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v3/Accounts.
Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.

Response (application/json)

200 OK
400 Bad Request
403 Forbidden
404 Not Found

OK

{
  "account": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Sample Account Type Name",
    "label": "John Smith",
    "type": "CACC",
    "currency": "GBP",
    "balances": [
      {
        "name": "Current Account",
        "amount": 2310.55,
        "currency": "GBP",
        "status": "VALU",
        "balanceLastUpdatedAt": "2025-04-19T10:02:00.964Z"
      }
    ],
    "minimumBalance": {
      "name": "Current Account",
      "amount": -200,
      "currency": "GBP",
      "status": "VALU"
    },
    "productType": "Segregated",
    "accountSubType": "SafeguardedPooled",
    "legalOwnerType": "Personal",
    "relationshipType": "Single",
    "status": "Enabled",
    "statusReason": "Other",
    "timestampCreated": "2025-02-19T11:32:10.934Z",
    "timestampModified": "2025-05-25T18:27:12.524Z",
    "iban": "GB12CLBK01020312345678",
    "bban": "CLBK01020312345678",
    "upic": "string",
    "cuid": "string"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

You can use the endpoint below to update the details of a Hub Account.

Amend a Hub Account

patch/v1/accounts/{accountId}

This endpoint is used to amend the properties of an existing real account.

Parameters

accountId string, path, Required
The unique identifier for the real account.
Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Request Payload (application/json)

status string
Use this field to set the status of the account. If closing or suspending the account, you should provide a StatusReason. If you are not updating the account's status, either use 'NotProvided' or omit this field.
Enum array
NotProvided, Enabled, Closed, Suspended
statusReason string
If the account Status is Closed or Suspended, use this field to provide a reason. Use 'Other' if no other options apply. Do not provide this field if you are updating the status to 'Enabled'.
Enum array
AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, FraudConfirmed, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute, Other
ownerName string
The name used to identify the legal owner of the account.
Minimum length
0
Maximum length
70
Pattern
^[^\|_\[\]<>^`~\\$]*$
legalOwnerType string
Nature of funds held in the account. Valid options include: Personal, Business.
Enum array
Personal, Business
relationshipType string
Operating nature of the account. Valid options include Single, Joint. If legalOwnerType is Business, then the relationshipType cannot be Joint.
Enum array
Single, Joint
minimumBalance number
The minimum allowable balance of the account (example: -£1000). Note that you must send a negative number to create an overdraft. This field can only be used if your organisation is an embedded banking client with an overdraft agreement in place; otherwise the request will be rejected.

request

{
  "status": "Closed",
  "statusReason": "AccountHolderDeceased",
  "ownerName": "John Smith",
  "legalOwnerType": "Personal",
  "relationshipType": "Single",
  "minimumBalance": 0
}

Code copied

Response (application/json)

204 No content
400 Bad Request
403 Forbidden
409 Conflict

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Conflict

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Before attempting to close a Hub Account, you should ensure you are subscribed to both the Account Closure Completed and Account Closure Failed webhooks.

To close a Hub Account, follow these steps:

Withdraw all funds from the account.
Use the POST /v1/accounts/{id}/closure endpoint to request closure.
Note: If the Hub Account is interest bearing, it must have a nominated account before it can be closed. If there is no interest to be paid, then you can close the account without defining a nominated account.
OPTIONAL You can check the closure status of a Hub Account using the GET /v1/accounts/{id}/closure endpoint.
You'll receive an Account Closure Completed webhook once the account has closed.

Account closure may fail due to the nominated account details being incorrect. If this happens, you'll be notified via the ClosureFailureReason field in the Account Closure Failed webhook.

If account closure fails and isn't resolved before the end of the month, then any accrued interest will be paid into the account. You'll need to fully withdraw these funds from the account again before reattempting closure.

Close a Hub Account

post/v1/accounts/{accountId}/closure

This endpoint is used to create an account closure request.

Parameters

accountId string, path, Required
The unique identifier for the account.
Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Request Payload (application/json)

closureReason string, Required
The reason for closing the account. Use 'Other' if no other options apply.
Enum array
AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, FraudConfirmed, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute, Other

request

{
  "closureReason": "AccountHolderDeceased"
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request
404 Not Found
409 Conflict

Accepted

{
  "accountClosure": {
    "accountId": "01234567-89ab-cdef-0123-456789abcdef",
    "closureReason": "AccountHolderDeceased",
    "closureStatus": "Pending"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Conflict

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Get account closure status

get/v1/accounts/{accountId}/closure

Get current status of the account closure request.

Parameters

accountId string, path, Required
The unique identifier for the account.
Authorization string, header, Required
Your API Token, obtained from the ClearBank Portal.

Response (application/json)

200 OK
400 Bad Request
404 Not Found

OK

{
  "accountClosure": {
    "accountId": "01234567-89ab-cdef-0123-456789abcdef",
    "accountStatus": "Closed",
    "closureStatus": "Complete",
    "closureFailureReasons": [
      "string"
    ],
    "accountModifiedDateTime": "2024-01-01T12:34:56.789+00:00"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

You can receive the following combinations of accountStatus and closureStatus from the GET /v1/accounts/{accountId}/closure endpoint:

accountStatus	closureStatus	Description
Enabled	None	No closure request submitted
Enabled	Pending	Closure requested, interest being calculated
Enabled	Failed	Closure request failed, see `closureFailureReasons` field for details
Suspended	Pending	Closure requested for suspended account, interest being calculated
Closed	Complete	Closure completed successfully

This webhook confirms the account has been closed. After you receive this webhook, any further requests to close the account will be rejected.

Request body

{
    "Type": "AccountClosureCompleted",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`AccountId`	Account identifier used to uniquely identify the account. Type: `string` Format: `GUID` Length: `36` Pattern: `^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$`
`ClosureReason`	Reason that the account was closed. Type: `string` Min. length: `1` Max. length: `100`
`AccountModifiedDateTime`	Date and time the account was last modified. Type: `string` Time Zone: `UTC` Format: `DateTime`
`Nonce`	Cryptographically secure number generated by ClearBank for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example Account Closure Completed webhook request body

{
    "Type": "AccountClosureCompleted",
    "Version": 1,
    "Payload":{
        "AccountId": "56de3483-a569-42eb-90cc-acf59661356f",
        "ClosureReason": "AccountSwitched",
        "TimestampCreated": "2024-07-19T13:31:30.8789344Z"
    },
    "Nonce": 1082937279
}

Example webhook response

{
    "Nonce": 1082937279
}

This webhook confirms the account has not been closed. If you receive this webhook, you should check the ClosureFailureReason field for more information on why the account closure has failed.

Account closure may fail due to the nominated account details being incorrect. In this scenario, you should retry the account closure through the relevant endpoint, ensuring that the correct nominated account details are submitted in the closure request.

Obtain details of the currently configured nominated account using the GET /v1/accounts/{accountId}/nominated-account endpoint.
OPTIONAL Correct the nominated account details using the PUT /v1/accounts/{accountId}/nominated-account endpoint.
Resend the account closure request.

Request body

{
    "Type":"AccountClosureFailed",
    "Version":1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`AccountId`	Account identifier used to uniquely identify the account. Type: `string` Format: `GUID`
`ClosureReason`	Reason that the account was closed. Type: `string`, `null` Min. length: `1` Max. length: `100`
`ClosureFailureReasons`	List of reasons the account failed to close. Type: `array` Min items: `1` Item type: `string` Min length: `1`
`AccountModifiedDateTime`	Date and time the account was last modified. Type: `string` Time Zone: `UTC` Format: `DateTime`
`Nonce`	Cryptographically secure number generated by ClearBank for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example account created webhook request body

{
    "Type":"AccountClosureFailed",
    "Version":1,
    "Payload":{
        "AccountId":"45b542a0-1915-49de-96d8-f2dc906d5cc9",
        "ClosureReason":"AccountHolderBankrupt",
        "ClosureFailureReasons":{
            "Account 45b542a0-1915-49de-96d8-f2dc906d5cc9 does not have a nominated account set"
        },
        "AccountModifiedDateTime":"2024-09-23T13:31:30.8789344Z"
    },
    "Nonce":108246778
}

Example webhook response

{
    "Nonce": 1082946778
}

Hub Accounts

Hub Accounts overview

Creating Hub Accounts

Create a Hub Account

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Associated and nominated accounts

Manage associated or nominated accounts

Add an associated or nominated account

Parameters

Request Payload (application/json)

Response (application/json)

Retrieve associated and nominated accounts

Parameters

Response (application/json)

Amend an associated or nominated account

Parameters

Request Payload (application/json)

Response (application/json)

Remove an associated or nominated account

Parameters

Response (application/json)

Manage nominated accounts

Set a nominated account

Parameters

Request Payload (application/json)

Response (application/json)

Get a nominated account

Parameters

Response (application/json)

Retrieve and update Hub Account information

Get all real accounts, including Hub Accounts

Parameters

Response (application/json)

Get information for a Hub Account

Parameters

Response (application/json)

Amend a Hub Account

Parameters

Request Payload (application/json)

Response (application/json)

Hub Account closure

Close a Hub Account

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Get account closure status

Parameters

Response (application/json)