Retrieves a specific user preference for the currently logged-in user

GET /api/users/preference/{preferenceId}

Success: 200 OK

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

Overview

Reads back one named preference value for the staff (back-office) user your access token belongs to, exactly as Creates or updates a user preference for the currently logged-in user stored it. The response body is the raw stored string, JSON-encoded — a bare "…", not an object wrapping it.

You cannot read another user's preferences with this endpoint. The user is taken from your access token, not from anything in the request.

{preferenceId} is the name of a preference type registered for the tenant, matched case-insensitively — not an opaque identifier from a previous response. An unregistered name fails with 400, and that is different from a registered name the user has never set, which succeeds with 200 and a body of null. Distinguish the two: 400 means fix your name, null means fall back to your own default.

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

Endpoint

GET {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 read, 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`, even if you have never stored a value under it. An empty segment fails with `400` and `preferenceId must be specified`.

Sample request

cURL

curl -X GET '{base_url}/api/users/preference/{preferenceId}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'

Sample response

200 OK

"string"

Errors

Status	Meaning	When
`400`	Bad request	`{preferenceId}` names no registered preference type for the tenant: `PreferenceId "{preferenceId}" is missing or invalid`. Note that a value stored moments earlier can still fail this way if the type was removed from the tenant's configuration in between.
`400`	Bad request	The path segment is empty: `preferenceId must be specified`.
`400`	Bad request	Your access token carries no signed-in user: `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`. A registered preference with no value saved for the user does not return `404` — it returns `200` with a body of `null`.
`500`	Internal server error	Any other unexpected server-side failure while reading the preference. Returned with no body.

This page as markdown · All pages · llms.txt