Update department

PUT /api/configuration/departments/{id}

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

Overview

Changes a department's description, its external reference, or the cost centre it reports to. Departments are the second level of the financial reporting structure — each department belongs to a cost centre, and products and charges are attributed through them. Only these three fields are writable.

This is a partial update, not a full replacement. Every field is applied only when it is present and non-null, so anything you omit or send as null keeps its current value. Sending only the field you want to change is safe here.

Empty strings behave differently from nulls, and differently between fields:

description: "" fails validation with Description cannot be blank, because the field carries a minimum length of 1.
reference: "" and costCentreId: "" pass validation. An empty reference overwrites the stored reference with an empty value. An empty costCentreId is not null, so it is checked against the cost centre list and rejected with Cost centre does not exist.

Validation order matters when you are debugging a 400: the cost centre is checked before the department is looked up, so a request naming both an unknown department and an unknown cost centre returns the cost centre 400, not a 404.

On success the response is 204 No Content and the change is visible on the next read. Note that the 404 for an unknown department has an empty body, so there is no message to key off.

Endpoint

PUT {base_url}/api/configuration/departments/{id}

{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.

Path parameters

Name	Type	Required	Description
`id`	string	Yes	Identifier of the department to change, as listed by `GET /api/configuration/departments`. Maximum 15 characters, matching the limit applied when departments are created. An empty path segment is rejected with `400 The ID cannot be empty`; an identifier that matches no department returns an empty-bodied `404`.

Request body

Field	Type	Required	Description
`description`	string	No	The department's name as it appears in finance listings and reporting. Between 1 and 255 characters when supplied — an empty string fails with `Description cannot be blank` and anything longer fails with `Description cannot be greater than 255 characters`. Omit it, or send null, to leave the current description alone.
`reference`	string	No	Your own or your finance system's reference for the department — free text, not validated against anything and not used by the platform for matching. Maximum 255 characters (`Reference cannot be greater than 255 characters`). Omit it, or send null, to leave the current value alone; an empty string is accepted and clears the stored reference.
`costCentreId`	string	No	The cost centre this department reports to, from `GET /api/configuration/cost-centres`. Maximum 15 characters (`Cost centre ID cannot be greater than 15 characters`). Any non-null value is checked against the existing cost centres and the request fails with `400 Cost centre {id} does not exist` if it is not found — including an empty string, which is checked rather than ignored. Omit it, or send null, to leave the department where it is. Reassigning a department here is what stops its former cost centre being locked from deletion.

Sample request

cURL

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

Errors

Status	Meaning	When
`400`	Bad request	The path identifier is empty or missing — body is the string `The ID cannot be empty`.
`400`	Bad request	Body validation failed: `description` empty (`Description cannot be blank`) or over 255 characters, `reference` over 255 characters, or `costCentreId` over 15 characters. The body is a validation error object keyed by field name.
`400`	Bad request	`costCentreId` was supplied but matches no cost centre — body is `Cost centre {id} does not exist`. Checked before the department itself is looked up.
`404`	Not found	No department matches the path identifier. The body is empty, so there is no message to distinguish this from other `404`s.
`500`	Internal server error	An unexpected server-side failure. No detail is returned.

This page as markdown · All pages · llms.txt