ClearBank

Flexible cash ISAs

Flexible cash ISAs overview

A cash ISA (Individual Savings Account) is a real savings deposit account held with ClearBank that is subject to tax benefits defined by the UK government. It can be used to send and/or receive payments once a nominated account has also been defined.

The balance of a cash ISA is held by ClearBank and can only be viewed via our API. Cash ISAs are reconciled for you by ClearBank. To open a cash ISA, your customer must provide you with their national insurance number and confirm they are a UK resident.

Because cash ISAs are structured differently to other GBP account types, you must use the endpoints defined on this page to interact with them. Do not use the endpoints listed on the Manage sterling accounts page.

You can create and manage customers with cash ISAs using the endpoints listed on the Retail customers page.

The sections below explain how to:

Set up a cash ISA

When creating a new cash ISA, you need to first create the account, then set up the nominated account.

To set up a cash ISA:

  1. Use the POST /v1/isas endpoint to create the account

    You cannot deposit funds into the cash ISA before the nominated account has been defined.

  2. After receiving the Account Created webhook, use the PUT /v1/accounts/{accountId}/nominated-account endpoint to define the nominated account for the cash ISA

    You can now deposit funds into the cash ISA.

The process is shown in this message flow diagram:

Submit the POST /v1/isas endpoint. Once you receive a 201 response, submit the PUT /v1/accounts/{accountId}/nominated-account to set a nominated account. Once you receive a 200 response, funds can now be added to the cash ISA.

The account is now open and fully operational. You can retrieve information on all ISAs by using the GET /v3/accounts endpoint and filtering for ISAs. You can also retrieve details on a specific cash ISA using the GET /v1/isas/{accountId} endpoint.

You can amend the details or the status of a cash ISA using the PATCH /v1/accounts/{accountId} endpoint.

To retrieve end of day balances for a cash ISA, use the camt.053 endpoints.

End of life for a cash ISA

There are several ways you can close a cash ISA. You need to choose the appropriate one based on what's happened in the account journey so far and what the customer wants to do with the account next.

ActionWhat this does
CloseCloses the account.
CancelCancels and closes the account without registering the account with the UK government. The account must be under 14 days old and must have had funds deposited.
Transfer outAllows you to transfer the account to another provider. Once transfer out has been successful, you then need to close the account.
DiscontinueOnly applicable where the ISA account holder is deceased. Triggers the payment of unpaid interest to allow for account closure.

You can use this diagram to validate if the account should be closed, cancelled or transferred out:

A decision tree diagram explaining the life cycle of a cash ISA.

The sections below explain how to:

Close

When closing a cash ISA, you must first withdraw funds before closing the account.

Before an account closure can be requested, the account balance must be zero. Funds can be withdrawn to a nominated account or another ClearBank account. If any interest has been accrued, it will be paid to the nominated account.

If the account balance is not zero, the request will be rejected. Account closure requests cannot be undone.

To close a cash ISA:

  1. Withdraw all funds from the cash ISA.
  2. Use the POST /v1/accounts/{accountId}/closure endpoint to request the account closure.

    This process is asynchronous. The cash ISA is now frozen. Once the request is accepted, the account closure is pending until, if the account has accrued interest, the last interest payment is calculated and paid. This interest payment will be made to the nominated account. Once the payment has completed, the account will be closed.

  3. OPTIONAL Use the GET /v1/accounts/{accountId}/closure endpoint to check whether the account has been closed.
  4. You will receive either the Account Closure Completed or Account Closure Failed webhook once the account closure process has completed.

If the account closure fails, re-request the closure.

The process is shown in this message flow diagram:

Submit the POST /v1/isas/{accountId}/cancellation endpoint. Once you receive a 202 response. As the process is asynchronous, you can check on the closure status using the GET /v1/accounts/{accountId}/closure endpoint. Once the closure is confirmed, you will receive either the Account Closure Completed or Account Closure Failed webhook.

Cancel

When cancelling a cash ISA, the account must be under fourteen days old. This endpoint also closes the account.

The cancellation period is based on the acceptance date field. For example, an account with the acceptance date of the 1st of the month can be cancelled up to 23:59 on the 14th day of the month.

Money must have already been deposited into the cash ISA. If no money has been deposited, or the account is over 14 days old, use the POST /v1/accounts/{accountId}/closure endpoint instead.

To cancel a cash ISA:

  1. Withdraw all funds from the cash ISA.
  2. Use the POST /v1/isas/{accountId}/cancellation to request the cancellation.

    This process is asynchronous. The cash ISA is now frozen. Once the request is accepted, the account closure is pending until, if the account has accrued interest, the last interest payment is calculated and paid. This interest payment will be made to the nominated account. Once the payment has completed, the account will be closed.

  3. OPTIONAL Use the GET /v1/accounts/{accountId}/closure endpoint to check whether the account has been cancelled.
  4. You will receive either the Account Closure Completed or Account Closure Failed webhook once the account cancellation process has completed.

The process is shown in this message flow diagram:

Message flow diagram of the cancellation process, as detailed above.

Discontinue

The process to discontinue a cash ISA account begins with the notification that the account holder is deceased. Once you have received the notification, use the PATCH /v1/accounts/{accountId} to update the status to Suspended using the statusReason of AccountHolderDeceased.

As per HMRC rules, if an ISA investor passes away, their account must be treated as 'continuing account of a deceased investor'. This allows the account to continue to accrue interest and benefit from the tax advantages of an ISA for the period beginning with the death of the account holder and ending either:

  • On the completion of the administration of the deceased's estate
  • 3 years since the date of death

Once either of these conditions are met, you will need to mark the account as discontinued. To do so, use the PATCH /v1/isas/{accountId}/discontinue endpoint to trigger the payment of any unpaid interest into the account. The account can then be closed as normal using the POST /v1/accounts/{accountId}/closure endpoint using the closureReason of AccountHolderDeceased.

The process is shown in this flow diagram:

Message flow diagram of process to discontinue an account following the death of the ISA account holder.

Manage customer ISA eligibility

Customers can be made ineligible for cash ISAs. While a customer is ineligible, they cannot pay funds into their cash ISA.
Ineligible customers should still be able to withdraw funds from their cash ISA.

Customers can be made ineligible for cash ISA subscriptions for these reasons:

  • You notified us that the customer's address is now outside the UK
  • You notified us that the customer's place of residence is now outside the UK
  • You provided us an invalid date of birth for the customer
  • You provided us an invalid National Insurance (NI) number for the customer

When a customer moves their address out of the UK, they can continue making subscriptions until the current tax year ends.
You should notify us of customer address changes via the PUT /v1/customers/retail/{customerId}/currentaddress endpoint.
If the customer's address returns to the UK in the next tax year, you should submit a new declaration of ISA eligibility.

When a customer moves their place of residence out of the UK, no further subscriptions can be made.
You should notify us of customer country of residence changes via the PATCH /v1/customers/retail/{customerId} endpoint.
If the customer's place of residence returns to the UK, you should notify us of this then submit a new declaration of ISA eligibility.

When a customer's date of birth or NI number is found to be invalid, no further subscriptions can be made.
Once you have obtained a corrected NI or date of birth for the customer, use the PATCH /v1/customers/retail/{customerId} endpoint to notify us of this then submit a new declaration of ISA eligibility.

You can submit a declaration of ISA eligibility using the POST /isas/{accountId}/declaration endpoint. Verify the customerEligibilityStatus field in the response has been set to Eligible.

You can also use the GET /v1/isas/{accountId} endpoint to check the customer's eligibility status at any time.

Setting up a cash ISA

Create a cash ISA

post/v1/isas

This endpoint is used to create an ISA.

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 account.

    Minimum length
    0
    Maximum length
    140
    Pattern
    ^[^<!|$*;^%_>`#@="~\[\]{}\\]*$
  • sortCode string, Required

    The sort code that the account should be created under.

    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}$
  • customerId string, Required

    The unique identifier of the customer that holds 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}$
  • applicationDate string, Required

    The date the ISA application got created.

  • acceptanceDate string, Required

    The date the ISA application got accepted.

request

{
"ownerName": "John Smith",
"sortCode": "010203",
"productId": "01234567-89ab-cdef-0123-456789abcdef",
"customerId": "01234567-89ab-cdef-0123-456789abcdef",
"applicationDate": "2024-01-01T00:00:00",
"acceptanceDate": "2024-01-01T00:00:00"
}
Code copied

Response (application/json)

  • 201 Created
  • 400 Bad Request
  • 404 Not Found
  • 422 Client Error

Created

{
"account": {
"accountId": "01234567-89ab-cdef-0123-456789abcdef",
"productId": "01234567-89ab-cdef-0123-456789abcdef",
"customerId": "01234567-89ab-cdef-0123-456789abcdef",
"accountName": "Adult Cash ISA",
"ownerName": "John Smith",
"iban": "GB12CLBK01020312345678",
"bban": "CLBK01020312345678",
"createdDateTime": "2024-01-01T12:34:56.789+00:00",
"applicationDate": "2024-01-01T00:00:00",
"acceptanceDate": "2024-01-01T00:00:00",
"cashIsaProductType": "Flex",
"cancellationGracePeriod": 0,
"remainingSubscriptionAllowance": 0,
"cashIsaStatus": "Active",
"customerEligibilityStatus": "Eligible",
"customerEligibilityStatusReasons": [
"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

Client Error

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

Associated Webhooks

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

Get cash ISA details

get/v1/isas/{accountId}

This endpoint is used to get the details of an ISA.

Parameters

  • accountId string, path, Required

    The unique identifier for the ISA. 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

{
"account": {
"closureDate": "2024-01-01T12:34:56.789+00:00",
"cancellationRequestDate": "2024-01-01T00:00:00",
"isCancellationRequestedWithinGracePeriod": true,
"netSubscription": 0,
"transferOutStatus": "FullTransferOutComplete",
"isDiscontinued": "False",
"accountId": "01234567-89ab-cdef-0123-456789abcdef",
"productId": "01234567-89ab-cdef-0123-456789abcdef",
"customerId": "01234567-89ab-cdef-0123-456789abcdef",
"accountName": "Adult Cash ISA",
"ownerName": "John Smith",
"iban": "GB12CLBK01020312345678",
"bban": "CLBK01020312345678",
"createdDateTime": "2024-01-01T12:34:56.789+00:00",
"applicationDate": "2024-01-01T00:00:00",
"acceptanceDate": "2024-01-01T00:00:00",
"cashIsaProductType": "Flex",
"cancellationGracePeriod": 0,
"remainingSubscriptionAllowance": 0,
"cashIsaStatus": "Active",
"customerEligibilityStatus": "Eligible",
"customerEligibilityStatusReasons": [
"string"
]
},
"halLinks": [
{
"name": "string",
"href": "string",
"templated": true
}
]
}
Code copied

Amend cash ISA details or status

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

    Current status of the account. Valid options include Not Provided, Enabled, Closed, Suspended.

    Enum array
    NotProvided, Enabled, Closed, Suspended
  • statusReason string

    Reason that the account is Closed or Suspended. Valid options include NotProvided, AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, FraudConfirmed, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute, Other.

    Enum array
    NotProvided, AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, Other, FraudConfirmed, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute
  • 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": "Enabled",
"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

Get all real accounts, including cash ISAs

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": 0,
"currency": "GBP",
"status": "VALU"
}
],
"minimumBalance": {
"name": "Current Account",
"amount": 0,
"currency": "GBP",
"status": "VALU"
},
"status": "Enabled",
"statusReason": "AccountHolderDeceased",
"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

Set a new ISA declaration

post/v1/isas/{accountId}/declaration

This endpoint is used to set a new ISA declaration if a customer has become eligible to subscribe to one again. A declaration must be set before any further subscriptions can be accepted.

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)

  • acceptanceDate string

    The UTC datetime that the customer's ISA declaration was submitted to you.

request

{
"acceptanceDate": "2024-07-11T01:51:13"
}
Code copied

Response (application/json)

  • 201 Success
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 409 Conflict
  • 422 Client Error

Success

{
"isaDeclaration": {
"accountId": "01234567-89ab-cdef-0123-456789abcdef",
"acceptanceDate": "2024-05-01T15:30:15",
"customerEligibilityStatus": "Eligible"
},
"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

Client Error

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

Subscribe to or withdraw from a cash ISA

You can use the Faster Payments endpoint to subscribe to or withdraw from a cash ISA.

Send Faster Payments

post/v3/payments/fps

Initiate a payment using the faster payments scheme. This endpoint is FTR compliant.

This endpoint works on a partial acceptance basis - meaning that you can submit 10 payments and only 6 of them may be accepted for processing. Each payment instruction is validated against the scheme specific rules as well as the ISO20022 specification. Currently, only payments through GBP are supported. We have listed possible currencies for future proofing of the API. The remittance information must be scheme compatible. Values exceeding the length limits of the scheme will be truncated. Missing remittance information will be replaced by a blank string.

Parameters

  • Authorization string, header, Required

    Your API Token, retrieved from the web 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.

Request Payload (application/json)

  • paymentInstructions array, Required

    Details of the payments to be made.

    Minimum length
    1
    Maximum length
    10

request

{
"paymentInstructions": [
{
"debtor": {
"legalEntityIdentifier": "string",
"address": "string"
},
"paymentInstructionIdentification": "string",
"debtorAccount": {
"identification": {
"iban": "string",
"other": {
"issuer": "string",
"identification": "string",
"schemeName": {
"code": "BBAN",
"proprietary": "string"
}
}
}
},
"creditTransfers": [
{
"paymentIdentification": {
"instructionIdentification": "string",
"endToEndIdentification": "string"
},
"amount": {
"currency": "GBP",
"instructedAmount": 0
},
"creditor": {
"name": "string",
"legalEntityIndentifier": "string"
},
"creditorAccount": {
"identification": {
"iban": "string",
"other": {
"issuer": "string",
"identification": "string",
"schemeName": {
"code": "BBAN",
"proprietary": "string"
}
}
}
},
"remittanceInformation": {
"structured": {
"creditorReferenceInformation": {
"reference": "string"
}
}
},
"enforceSendToScheme": true
}
]
}
]
}
Code copied

Response (application/json)

  • 202 Accepted
  • 400 Bad Request
  • 404 Not Found
  • 422 Client Error

Accepted

{
"transactions": [
{
"endToEndIdentification": "string",
"response": "Accepted"
}
],
"halLinks": [
{
"name": "string",
"href": "string",
"templated": true
}
]
}
Code copied

Bad Request

{
"errors": {
"property1": [
"string"
],
"property2": [
"string"
]
},
"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}
Code copied

Client Error

{
"errors": {
"property1": [
"string"
],
"property2": [
"string"
]
},
"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}
Code copied

Associated Webhooks

Closing a cash ISA

Close a cash ISA

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

    Reason for the account closure request. Valid options include AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, FraudConfirmed, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute, Other.

    Enum array
    NotProvided, AccountHolderBankrupt, AccountHolderDeceased, AccountSwitched, CompanyNoLongerTrading, DissatisfiedCustomer, DuplicateSoleTraderAccount, FinancialCrime, FraudFirstParty, FraudThirdParty, Other, FraudConfirmed, InternallyDormant, KYCRequired, LegallyDisputed, PotentialSanctionedIndividual, SanctionedIndividual, SuspectMoneyLaundering, TransactionDispute

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": "Complete"
},
"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

Associated Webhooks

Cancel a cash ISA

post/v1/isas/{accountId}/cancellation

This endpoint is used to cancel an ISA.

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)

  • cancellationRequestDate string, Required

    The date the ISA cancellation was requested.

request

{
"cancellationRequestDate": "2024-01-01T00:00:00"
}
Code copied

Response (application/json)

  • 202 Accepted
  • 400 Bad Request
  • 404 Not Found
  • 409 Conflict
  • 422 Client Error

Accepted

{
"isaAccountCancellation": {
"accountId": "01234567-89ab-cdef-0123-456789abcdef",
"cancellationRequestDate": "2024-01-01T00:00:00",
"isCancellationRequestedWithinGracePeriod": true,
"cancellationGracePeriod": 0
},
"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

Discontinue a cash ISA

patch/v1/isas/{accountId}/discontinue

This endpoint is used to discontinue an ISA.

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.

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

Get cash ISA 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

Transfer in

ClearBank supports full or partial transfers in of cash ISAs.

During the transfer in process, the previous ISA manager will transfer the cash ISA funds to a transfer in hub account created during onboarding. Once you have received the transfer history form from them and submitted it to us, you can then move funds from the hub in account into the cash ISA.

If you want to reject an existing transfer in request, use the POST /v1/isas/{accountId}/transfer-in/{transferInId}/rejection endpoint.

To transfer in a cash ISA:

  1. If a cash ISA doesn't already exist, you'll need to set up a cash ISA first.
  2. Use the POST /v1/isas/{accountId}/transfer-in endpoint.

    You must provide a unique payment reference in the PaymentReference field when calling this endpoint. This reference will be used for reconciliation when the funds enter the transfer in or leave the transfer out hub.

  3. When the previous manager of the cash ISA moves funds into the transfer hub, you will receive the Transaction Settled webhook. They will also send you the transfer history form.
  4. Use the PUT /v1/isas/{accountId}/transfer-in/{transferInId}/transfer-history-form endpoint to submit the transfer history form to us.

    OPTIONAL To check the status of a transfer in, use the GET /v1/isas/{accountId}/transfer-in/{transferInId} endpoint.

  5. Once the transfer in has been approved, move the funds from the transfer hub to the cash ISA.

Message flow diagram of the transfer in process, as detailed above.

Transfer in a cash ISA

post/v1/isas/{accountId}/transfer-in

This endpoint is used to initiate an ISA transfer in.

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)

  • previousIsaManagerName string, Required

    The name of the previous ISA manager.

  • previousIsaSortCode string

    The sort code of the previous ISA account.

  • previousIsaAccountNumber string

    The account number of the previous ISA account.

  • previousIsaRollNumber string

    The building society identification number for the previous ISA account.

  • transferInType string, Required

    The type of previous ISA being transferred in.

  • paymentReference string, Required

    The payment reference to be used for crediting account.

request

{
"previousIsaManagerName": "Investment Bank",
"previousIsaSortCode": "010203",
"previousIsaAccountNumber": "01234567",
"previousIsaRollNumber": "ROLL234567",
"transferInType": "CashIsa",
"paymentReference": "0123456789abcdef01"
}
Code copied

Response (application/json)

  • 201 Success
  • 400 Bad Request
  • 404 Not Found
  • 422 Client Error

Success

{
"isaAccountTransferIn": {
"cashIsaTransferInId": "01234567-89ab-cdef-0123-456789abcdef",
"transferInStatus": "AwaitingFunds",
"previousIsaManagerName": "Investment Bank",
"previousIsaSortCode": "010203",
"previousIsaAccountNumber": "01234567",
"previousIsaRollNumber": "ROLL234567",
"transferInType": "CashIsa",
"paymentReference": "0123456789abcdef01"
},
"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

Submit a transfer history form

put/v1/isas/{accountId}/transfer-in/{transferInId}/transfer-history-form

This endpoint is used to submit a Transfer History Form

Parameters

  • accountId string, path, Required

    The unique identifier for the account.

  • transferInId string, path, Required

    The unique identifier for the transfer-In Id.

  • 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)

  • dateOfTransfer string, Required

    The date of transfer of the transfer history form

  • transferAmount number, Required

    The amount of the money transfer

  • currentTaxYearSubscriptionAmount number, Required

    The current tax year subscription amount

  • dateOfFirstSubscriptionInCurrentTaxYear string

    The date of first subscription in current tax year

request

{
"dateOfTransfer": "2024-05-01T00:00:00",
"transferAmount": "200.00",
"currentTaxYearSubscriptionAmount": "20.00",
"dateOfFirstSubscriptionInCurrentTaxYear": "2024-05-01T00:00:00"
}
Code copied

Response (application/json)

  • 201 Created
  • 400 Bad Request
  • 404 Not Found
  • 422 Client Error

Created

{
"cashIsaTransferHistoryForm": {
"dateOfTransfer": "2024-05-01T00:00:00",
"transferAmount": "200.00",
"currentTaxYearSubscriptionAmount": "20.00",
"dateOfFirstSubscriptionInCurrentTaxYear": "2024-05-01T00:00:00",
"cashIsaTransferInId": "B194FCAC-22CA-4FD2-A413-12F602AACDB2",
"transferInStatus": "AwaitingFunds",
"previousIsaManagerName": "Investment Bank",
"previousIsaSortCode": "010203",
"previousIsaAccountNumber": "01234567",
"previousIsaRollNumber": "ROLL234567",
"transferInType": "CashIsa",
"paymentReference": "0123456789abcdef01"
},
"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

Get information on a transfer in

get/v1/isas/{accountId}/transfer-in/{transferInId}

This endpoint is used to get the transfer in details of an ISA.

Parameters

  • accountId string, path, Required

    The unique identifier for the account.

  • transferInId string, path, Required

    The unique identifier for the transfer in.

  • Authorization string, header, Required

    Your API Token, obtained from the ClearBank Portal.

Response (application/json)

  • 200 OK
  • 404 Not Found

OK

{
"transferIn": {
"cashIsaTransferInId": "01234567-89ab-cdef-0123-456789abcdef",
"accountId": "01234567-89ab-cdef-0123-456789abcdef",
"transferInStatus": "AwaitingFunds",
"previousIsaManagerName": "ClearBank Limited",
"previousIsaSortCode": "010203",
"previousIsaAccountNumber": "12345678",
"previousIsaRollNumber": "12345678",
"transferInType": "CashIsa",
"paymentReference": "my-payment-reference",
"dateOfTransfer": "2024-01-15T00:00:00",
"transferAmount": 0,
"currentTaxYearSubscriptionAmount": 0,
"dateOfFirstSubscriptionInCurrentTaxYear": "2024-01-01T00:00:00"
},
"halLinks": [
{
"name": "string",
"href": "string",
"templated": true
}
]
}
Code copied

Reject a transfer in

post/v1/isas/{accountId}/transfer-in/{transferInId}/rejection

This endpoint is used to reject an existing customer's transfer-in request on their ISA

Parameters

  • accountId string, path, Required

    The unique identifier for the account.

  • transferInId string, path, Required

    The unique identifier for the transfer in.

  • 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.

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 404 Not Found
  • 422 Client Error

OK

{
"rejectTransferInIsaAccount": {
"cashIsaTransferInId": "01234567-89ab-cdef-0123-456789abcdef",
"accountId": "01234567-89ab-cdef-0123-456789abcdef",
"transferInStatus": "Rejected",
"previousIsaManagerName": "ClearBank Limited",
"previousIsaSortCode": "010203",
"previousIsaAccountNumber": "12345678",
"previousIsaRollNumber": "ROLL234567",
"transferInType": "CashIsa",
"paymentReference": "0123456789abcdef01",
"dateOfTransfer": "2024-01-15T00:00:00",
"transferAmount": "400.00",
"currentTaxYearSubscriptionAmount": "400.00",
"dateOfFirstSubscriptionInCurrentTaxYear": "2024-01-01T00: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

Transfer out

You can also transfer a cash ISA to another provider. Once the transfer out is successful and the waiting period has completed, you'll need to close the account using the POST /v1/accounts/{accountId}/closure endpoint.

During the transfer out process, you move funds to a transfer out hub account created during onboarding. The cash ISA is then frozen. If the transfer out is successful, you can then move the funds from the transfer out hub to the new provider's account. There is a mandatory 15 day waiting period before you can close the account. If you requested a transfer out on the 1st of the month, the waiting period ends at 00:00 on the 16th. After that, you can close the account.

If the transfer out fails, the new provider will provide you a reason the transfer failed and they will return funds to the transfer out hub. Use the POST /v1/isas/{accountId}/transfer-outs/rejection endpoint to let ClearBank know the transfer out was unsuccessful and to unfreeze the account and return the account to the state it was before you requested the transfer out. Once the account is unfrozen, transfer the funds back into the cash ISA. The cash ISA will now continue to exist.

To transfer out a cash ISA:

  1. Use the POST /v1/isas/{accountId}/transfer-outs.

    The cash ISA is now frozen. Only accrued interest, if any, can be credited to the account, and only the full balance can be withdrawn from the account.

  2. Once the account has been credited the final interest payment, withdraw the full balance of the account to the transfer out hub account created during onboarding. From there, you can send the funds to the new provider.
  3. Wait at least the remainder of the 15 working day waiting period to ensure the transfer out has been successful.
  4. Once the transfer has successfully completed, use the POST /v1/accounts/{accountId}/closure endpoint to request the account closure.
  5. OPTIONAL Use the GET /v1/accounts/{accountId}/closure endpoint to check whether the account has been closed.
  6. You will receive either the Account Closure Completed or Account Closure Failed webhook once the account closure process has completed.

The process is shown in this message flow diagram:

Message flow diagram of the transfer out path, as detailed above.

Transfer out a cash ISA

post/v1/isas/{accountId}/transfer-outs

This endpoint is used to transfer an ISA to another provider.

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)

  • transferOutRequestDate string, Required

    The date the ISA transfer out was requested.

  • transferOutEffectiveDate string, Required

    The date the ISA transfer out should be in effect requested.

request

{
"transferOutRequestDate": "2024-01-01T00:00:00",
"transferOutEffectiveDate": "2024-01-01T00:00:00"
}
Code copied

Response (application/json)

  • 201 Success
  • 400 Bad Request
  • 404 Not Found
  • 422 Client Error

Success

{
"isaAccountTransferOut": {
"accountId": "01234567-89ab-cdef-0123-456789abcdef",
"cashIsaStatus": "Active",
"transferOutStatus": "InProgress",
"transferOutRequestDate": "2024-01-01T00:00:00",
"transferOutEffectiveDate": "2024-01-01T00: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

Reject a transfer out

post/v1/isas/{accountId}/transfer-outs/rejection

This endpoint is used to reject a transfer out of the ISA.

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.

Response (application/json)

  • 200 OK
  • 404 Not Found
  • 422 Client Error

OK

{
"isaAccountRejectTransferOut": {
"accountId": "01234567-89ab-cdef-0123-456789abcdef",
"transferOutStatus": "Rejected",
"transferOutRejectionDate": "2024-01-01T00:00:00"
},
"halLinks": [
{
"name": "string",
"href": "string",
"templated": true
}
]
}
Code copied

Client Error

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