Create department

POST /api/configuration/departments

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

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

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

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.

This page as markdown · All pages · llms.txt