Create bank details
POST /api/configuration/bank-details
Success: 201 Created
- Products: Operator (
FOH) - Features: Front of House Generic Access (
FOHGENERIC)
Overview
Creates a bank record — a sort code with the bank's name, branch address and telephone number. These records are the reference list of banks that site bank accounts and Direct Debit collections are attached to; creating one does not create an account, a mandate or any payment configuration.
You choose the identifier. The sortCode you send is the bank's identifier; there is no generated id. It must be unique within your tenant, so this call is safe to treat as "create once": a retry with the same sortCode returns 409 rather than creating a duplicate or overwriting the existing record. To change an existing bank, use PUT /api/configuration/bank-details/{sortCode} instead.
A success returns 201 Created with an empty body. Nothing is echoed back, so the only identifier you have afterwards is the sortCode you sent.
Endpoint
POST {base_url}/api/configuration/bank-details
{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
sortCode | string | Yes | The bank sort code, which doubles as the bank's identifier — you choose it and the platform does not generate one. Must not be empty and must not exceed 6 characters, so send the digits only (112233), not the hyphenated form (11-22-33), which is 8 characters and fails validation. Must be unique within your tenant: a sort code that already exists is rejected with 409. |
name | string | Yes | The bank's name, as it appears in bank listings and on paperwork. Must not be empty and must not exceed 25 characters — long names such as building societies' will need abbreviating. |
branchName | string | No | The specific branch this sort code belongs to, distinguishing it from other branches of the same bank. Maximum 25 characters. Omit it and it is left null. |
propertyName | string | No | First line of the branch address — the building name or number. Maximum 25 characters. Address fields are saved as sent and are not validated against any address lookup, so nothing checks that propertyName, street, town and postcode describe a real address. Omit it and it is left null. |
street | string | No | Street line of the branch address. Maximum 25 characters. Omit it and it is left null. |
locality | string | No | The district or neighbourhood line of the branch address, sitting between street and town. Maximum 25 characters. Omit it and it is left null. |
town | string | No | Town or city of the branch address. Maximum 25 characters. Omit it and it is left null. |
region | string | No | County, state or region of the branch address. Maximum 25 characters. Free text — it is not validated against a list of counties. Omit it and it is left null. |
country | string | No | Country of the branch address. Maximum 25 characters. Free text, not an ISO country code and not validated against any list. Omit it and it is left null. |
postcode | string | No | Postcode of the branch address. Maximum 10 characters. Format is not validated. Omit it and it is left null. |
telephone | string | No | Contact telephone number for the branch. Maximum 25 characters, kept as a string so spaces, + and extensions are preserved. Format is not validated. Omit it and it is left null. |
Sample request
curl -X POST '{base_url}/api/configuration/bank-details' \
-H 'Authorization: Bearer {accessToken}' \
-H 'X-Use-SSO: true' \
-H 'Content-Type: application/json' \
-d '{
"sortCode": "string",
"name": "string",
"branchName": "string",
"propertyName": "string",
"street": "string",
"locality": "string",
"town": "string",
"region": "string",
"country": "string",
"postcode": "string",
"telephone": "string"
}'Response fields
This endpoint returns no response body. A success is 201 Created with an empty payload and a Location header of the form {base_url}/api/configuration/bank-details?createdSortCode={sortCode} — note that it points back at this POST route with the sort code as a query string, not at a retrievable resource, so do not follow it. Read your bank record back with GET /api/configuration/bank-details/{sortCode} instead.
Sample response
HTTP/1.1 201 Created
Location: {base_url}/api/configuration/bank-details?createdSortCode={sortCode}
Content-Length: 0Errors
| Status | Meaning | When |
|---|---|---|
400 | Bad request | sortCode or name is missing or empty, or any field exceeds its maximum length — most often sortCode sent in hyphenated form (11-22-33), which is 8 characters against a 6-character limit. Returned as a validation problem document (application/problem+json, RFC 7807) with an errors map keyed by field name, not as a plain string, so parse it differently from the 409 body. |
409 | Conflict | "The bank detail with sort code {sortCode} already exists" — returned as a plain string. The existing bank is left untouched; switch to PUT /api/configuration/bank-details/{sortCode} to change it. |
500 | Internal server error | Any other failure, including an unexpected server-side failure while saving. No detail is returned. |