# Create bank details

`POST /api/configuration/bank-details`

- **Success:** `201 Created`
- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Create bank details](https://support.gladstonesoftware.cloud/reference/configuration/create-bank-details)

## 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](../../guides/authenticating-with-gladstone-apis.md).

## 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

```bash title="cURL"
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 title="201 Created"
HTTP/1.1 201 Created
Location: {base_url}/api/configuration/bank-details?createdSortCode={sortCode}
Content-Length: 0
```

## Errors

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