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

DELETE /api/users/preference/{preferenceId}

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

Overview

Removes one named preference value for the staff (back-office) user your access token belongs to, so that Retrieves a specific user preference for the currently logged-in user goes back to returning null and your client falls back to its own default. Returns 204 No Content with no body. The deletion is not recoverable through this API — read the value first if you may need it.

The call is idempotent: deleting a preference the user has never set still returns 204, so a 204 is not proof that anything was removed. It only ever affects one user's stored value; the preference type itself stays registered for the tenant and other users are untouched.

You cannot delete another user's preferences with this endpoint. The user is taken from the LoggedInUser value the gateway derives 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.

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

Endpoint

DELETE {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 clear, 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`. An empty segment fails with `400` and `preferenceId must be specified`. Deleting `PreferredSiteId` removes the user's default site, which the user-retrieval endpoints then report as `preferredSiteId: null`.

Sample request

cURL

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

Errors

Status	Meaning	When
`400`	Bad request	`{preferenceId}` names no registered preference type for the tenant: `PreferenceId "{preferenceId}" is missing or invalid`. Also returned, with no body, when the delete loses a concurrency check because the preference was changed by someone else between read and write — retry in that case.
`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`. A registered preference the user has never set does not return `404` — the call succeeds with `204`.
`409`	Conflict	The preference could not be deleted. Returned with no body.
`500`	Internal server error	Any other unexpected server-side failure while deleting the preference. Returned with no body.

This page as markdown · All pages · llms.txt