# Create department

`POST /api/configuration/departments`

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

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

## Overview

Creates a department and attaches it to an existing cost centre. Departments are the level at which sales and financial postings are categorised, so most products and services eventually point at one.

The cost centre must already exist — create it with [Create cost centre](create-cost-centre.md) first and pass the identifier it returned. A `costCentreId` that does not resolve fails with `400` before anything is saved.

**A successful call returns `201` with the body `"Created"` and the new identifier in the `Location` header**, which points at the GET route for the department. The body does not carry the id.

**Supply your own `id` to make the call safely retryable.** With an explicit `id`, a repeat request returns `409`. With `id` omitted, each attempt allocates a fresh generated code, so a retry after a timeout leaves two departments behind.

A duplicate `id` returns `409`, and the department is never partially saved.

## Endpoint

`POST {base_url}/api/configuration/departments`

`{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 |
|-------|------|----------|-------------|
| `id` | string | No | The department code, unique within your tenant and quoted wherever a department is selected. Maximum 15 characters. Omit the field entirely — or send it as JSON `null` — and the system allocates the next code in the sequence `DEPT` followed by 11 digits, for example `DEPT00000000001`, returned in the `Location` header. Beware that an **empty string is not treated as absent**: `""` is taken as a literal id and the request fails. Reusing an existing code returns `409` with `Primary key {id} already exists`. |
| `description` | string | Yes | The human-readable name of the department, as it appears in reporting and in point-of-sale selection lists. Required, and no longer than 255 characters. |
| `reference` | string | No | Your own cross-reference for the department, typically the code it carries in the finance system you are reconciling against. Maximum 255 characters. Omit it, or send null, to leave it blank; the value is saved as given and is not validated. |
| `costCentreId` | string | Yes | The cost centre this department rolls up to, as returned in the `Location` header by [Create cost centre](create-cost-centre.md) or listed by the cost centre endpoints. Required, maximum 15 characters. It is checked before anything is saved: a code that matches no cost centre fails with `400` and `Cost centre {id} does not exist`. The cost centre is not created for you. |

## Sample request

```bash title="cURL"
curl -X POST '{base_url}/api/configuration/departments' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "string",
  "description": "string",
  "reference": "string",
  "costCentreId": "string"
}'
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | `description` or `costCentreId` is missing, or any field exceeds its length limit. The body is a validation error object keyed by field name. |
| `400` | Bad request | `costCentreId` matches no existing cost centre — `Cost centre {id} does not exist`. Nothing is saved. |
| `409` | Conflict | A department already exists with the `id` you supplied — `Primary key {id} already exists`. Nothing is partially saved. |
| `500` | Internal server error | Any other unexpected server-side failure. The body is empty. |