Creates or updates a user preference for the currently logged-in user

POST /api/users/preference/{preferenceId}

Success: 201 Created

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

Overview

Stores one named preference value against the staff (back-office) user your access token belongs to. It is an upsert: the first call for a given preference name creates the value and returns 201 Created, and every later call overwrites it and returns 204 No Content. Check the status code if you need to tell the two apart — neither returns a body.

You cannot target another user with this endpoint. The user is taken from the LoggedInUser value the gateway derives from your access token, not from anything in the request. To change another user's settings you need Updates user preferences and application settings for a specific user, which takes a username in the path — but note that it writes a different, fixed set of settings, not this open key/value store.

{preferenceId} is not an opaque identifier you get from a previous response. It is the name of a preference type registered for the tenant, matched case-insensitively. A name that is not registered is rejected with 400 before anything is stored — this is the single most common failure on these four endpoints, and the reason a value can appear to save and then not read back. Two names the platform itself uses are PreferredSiteId (which Updates the details and settings for a specific administrative user writes through to) and BookingSheetFavourite.

The route requires the CentreManagement.CentreManagement.Access permission on your token in addition to the scopes above.

Endpoint

POST {base_url}/api/users/preference/{preferenceId}

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

Path parameters

Name	Type	Required	Description
`preferenceId`	string	Yes	The name of the preference type to write, matched case-insensitively against the preference types registered for the tenant — `PreferredSiteId`, for example. A name that is not registered fails with `400` and `PreferenceId "{preferenceId}" is missing or invalid`; it is not created on demand. An empty segment fails with `400` and `preferenceId must be specified`.

Request body

Field	Type	Required	Description
`data`	string	No	The value to store, as free text up to 4000 characters. The platform does not interpret it, so anything that fits in a string works — a site code, a JSON document, a serialised list of favourites — and it is returned byte-for-byte by Retrieves a specific user preference for the currently logged-in user. Omitting it or sending `null` is not "leave the current value alone": it overwrites the stored value with null while keeping the preference itself in place. To remove the preference outright use Deletes a specific user preference for the currently logged-in user. Exceeding 4000 characters is not validated up front and surfaces as a `500`.

Sample request

cURL

curl -X POST '{base_url}/api/users/preference/{preferenceId}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": "string"
}'

Sample response

201 Created

"string"

Errors

Status	Meaning	When
`400`	Bad request	`{preferenceId}` names no registered preference type for the tenant: `PreferenceId "{preferenceId}" is missing or invalid`. Registering the type is a configuration task outside this API.
`400`	Bad request	The path segment is empty: `preferenceId must be specified`.
`400`	Bad request	Your access token carries no signed-in user, so the gateway supplied no `LoggedInUser` value: `No username in headers`. Machine-to-machine tokens with no user behind them hit this.
`404`	Not found	The signed-in user from your token has no user account in the tenant: `User "{username}" could not be found`.
`409`	Conflict	A preference already exists for this combination of application, preference type and user: `This entry already exists in the database`.
`500`	Internal server error	Any other unexpected server-side failure, including `data` exceeding the 4000-character limit. Returned with no body.

This page as markdown · All pages · llms.txt