Get department by ID

GET /api/configuration/departments/{id}

Success: 200 OK

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

Overview

Returns one department, together with the cost centre it belongs to. Departments are the lower level of the operator's two-level financial reporting structure, and they are what saleable items hang off: every product belongs to exactly one department, and every department belongs to exactly one cost centre. Reach for this endpoint when you hold a department id and need its name, or need to know which cost centre sits above it, without pulling the whole list.

A department is purely an accounting classification. It does not affect pricing, availability, permissions or booking rules — it determines only how a product's income is grouped for reporting.

Departments are operator-defined and tenant-scoped. Gladstone does not allocate the ids, they are not consistent between tenants, and there is no standard list, so discover them at runtime through Get all departments rather than hard-coding them.

There is no active, inactive or archived flag on a department, so every department the operator has created is returned until it is explicitly deleted. A successful response does not imply the department is still in use.

One staleness behaviour is worth planning around. Creating, updating or deleting a department is reflected immediately, but editing a cost centre is not: after an operator renames a cost centre, this endpoint can keep returning the old costCentreDescription for up to six hours while Get cost centre by ID already returns the new one. If the two must agree, read the cost centre directly. A newly created department is always found, so only the embedded cost centre text goes stale, never the existence of the record.

Endpoint

GET {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	The department's identifier, unique within your tenant; maximum 15 characters. Send it exactly as it was returned to you. Case handling is inconsistent: sometimes the id must match character for character, and sometimes a different case matches. Do not rely on either behaviour. Take the value from Get all departments, or from a product's department reference. Ids are chosen by the operator when the department is created; if they leave it blank, the platform generates one of the form `DEPT` followed by 11 digits, zero-padded, such as `DEPT00000000012`. Do not depend on that shape — an operator-supplied id can be any string of 15 characters or fewer.

Sample request

cURL

curl -X GET '{base_url}/api/configuration/departments/{id}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'

Response fields

Field	Type	Description
`id`	string	The department's identifier as the platform holds it, maximum 15 characters. This is the value products carry as their department reference, and the value to send when updating or deleting the department.
`description`	string	The operator's label for the department, maximum 255 characters, and the only human-readable name it has. Use it for display only: it is not unique, so two departments may share a description, and it is not translated. It is mandatory when a department is created and cannot be updated to a blank string, but a record created outside this API can return `null`.
`reference`	string	An optional free-text field, maximum 255 characters, kept verbatim and never validated, parsed or matched by the platform. Returned as `null` when the operator has not set one.
`costCentreId`	string	The cost centre this department rolls up into, maximum 15 characters. It is never `null` and never empty, and both the create and update endpoints reject a cost centre id that does not exist. A department cannot be moved out of a cost centre, only moved to a different one, and a cost centre cannot be deleted while any department still points at it.
`costCentreDescription`	string	The cost centre's own `description`, copied into this response so you do not have to make a second call. It is a denormalised display value: it is `null` whenever the cost centre itself has no description, and it can lag behind the cost centre record by up to six hours after a rename — see the staleness note in the overview. Never key on it; use `costCentreId`.

Sample response

200 OK

{
  "id": "string",
  "description": "string",
  "reference": "string",
  "costCentreId": "string",
  "costCentreDescription": "string"
}

Errors

Status	Meaning	When
`404`	Not found	No department with that id exists in this tenant. The response body is empty — no message, no problem-details object — so branch on the status code alone. A mistyped id and a deleted department are indistinguishable here, and so is an id whose case happens not to match.
`500`	Internal server error	An unexpected server-side failure while reading the record. The response has no body and says nothing about your request, so retry rather than changing the id.

This page as markdown · All pages · llms.txt