# Updates user preferences and application settings for a specific user

`PUT /api/users/{username}/preferences`

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

HTML version: [Updates user preferences and application settings for a specific user](https://support.gladstonesoftware.cloud/reference/users/updates-user-preferences-and-application-settings-for-a-specific-user)

## Overview

Sets the avatar and default site of a named staff (back-office) user. Returns `204 No Content` with no body. Unlike the endpoints under `/api/users/preference/{preferenceId}`, which only ever act on the user behind your own access token, this one takes the target user in the path — so use it when an administrator is configuring somebody else's account.

**Read the request body table carefully: only `details.avatarId` and `details.preferredSiteId` are applied.** The whole `preferences` object — `favourites`, `bookingSheetFavourites`, `languageId`, `accessibilitySettings` and `system` — is accepted by the API and then ignored. Sending it changes nothing and returns `204`, which is indistinguishable from success. If you need to store those settings, use [Creates or updates a user preference for the currently logged-in user](creates-or-updates-a-user-preference-for-the-currently-logged-in-user.md), which genuinely saves key/value preferences — subject to its own limitation that it can only write for the caller's own account.

The `details` object is not optional in practice. Omitting it produces a `500`, and supplying it with a blank `avatarId` produces a `400`, so every call must carry an avatar even when all you are changing is the site.

The account must be fully set up for this endpoint or the call returns `404`. On numeric-role tenants — those whose users' `roleId` values are numbers in [Retrieves all administrative users configured in the system](retrieves-all-administrative-users-configured-in-the-system.md) — this endpoint returns `404` for every account, including accounts that [Retrieves detailed information for a specific administrative user](retrieves-detailed-information-for-a-specific-administrative-user.md) returns quite happily. Set `avatarId` and `preferredSiteId` through [Updates the details and settings for a specific administrative user](updates-the-details-and-settings-for-a-specific-administrative-user.md) instead if you hit that.

## Endpoint

`PUT {base_url}/api/users/{username}/preferences`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `username` | string | Yes | The sign-in name of the account to configure, as returned in `[].username` by [Retrieves all administrative users configured in the system](retrieves-all-administrative-users-configured-in-the-system.md). Matched exactly, and this — not `id` in the body — is the value used. On numeric-role tenants, and for any account that is not fully set up, the call fails with `404`. |

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Ignored. The account is identified solely by the `username` in the path; a mismatched or absent `id` has no effect and triggers no validation error. |
| `preferences` | object | No | Accepted and ignored in full. None of the fields nested beneath it are read or stored by this endpoint, and sending them still returns `204`. |
| `preferences.favourites` | string | No | Ignored — see `preferences`. |
| `preferences.bookingSheetFavourites` | array of object | No | Ignored — see `preferences`. Booking-sheet favourites are saved under the preference name `BookingSheetFavourite` via [Creates or updates a user preference for the currently logged-in user](creates-or-updates-a-user-preference-for-the-currently-logged-in-user.md), which is the working route for this data. |
| `preferences.bookingSheetFavourites[].id` | string | No | Ignored — see `preferences`. |
| `preferences.bookingSheetFavourites[].description` | string | No | Ignored — see `preferences`. |
| `preferences.languageId` | string | No | Ignored — see `preferences`. |
| `preferences.accessibilitySettings` | object | No | Ignored — see `preferences`. |
| `preferences.accessibilitySettings.zoomLevel` | integer (int32) | No | Ignored — see `preferences`. |
| `preferences.system` | object | No | Ignored — see `preferences`. |
| `preferences.system.receiptLayoutId` | string | No | Ignored — see `preferences`. |
| `preferences.system.hardwareProfileId` | string | No | Ignored — see `preferences`. |
| `details` | object | Yes | The only part of the request that is applied. Omitting it returns `500` rather than `400` — always send it. |
| `details.avatarId` | string | Yes | The profile image the back office shows for this user. Blank or omitted fails with `400` and `The avatar ID must be given a value`, which makes it mandatory in practice — resend the account's current `avatarId` when you only mean to change the site. Not validated against any list of known images. |
| `details.preferredSiteId` | string | No | The site this user works at by default. It must be a real site (`400`, `The given preferred site doesn't exist.`) and must belong to the site group already recorded on the account (`400`, `The preferred site ID must be contained in the given site group.`) — this endpoint cannot move a user between site groups, so change the group first with [Updates the details and settings for a specific administrative user](updates-the-details-and-settings-for-a-specific-administrative-user.md). Omitting it or sending an empty string leaves the current default site unchanged; there is no way to clear it here. |

## Sample request

```bash title="cURL"
curl -X PUT '{base_url}/api/users/{username}/preferences' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "string",
  "preferences": {
    "favourites": "string",
    "bookingSheetFavourites": [
      {
        "id": "string",
        "description": "string"
      }
    ],
    "languageId": "string",
    "accessibilitySettings": {
      "zoomLevel": 1
    },
    "system": {
      "receiptLayoutId": "string",
      "hardwareProfileId": "string"
    }
  },
  "details": {
    "avatarId": "string",
    "preferredSiteId": "string"
  }
}'
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | `details.avatarId` is missing or blank: `The avatar ID must be given a value`. Checked before the user is looked up, so this fires even for a username that does not exist. |
| `400` | Bad request | `details.preferredSiteId` names a site that does not exist: `The given preferred site doesn't exist.` |
| `400` | Bad request | `details.preferredSiteId` names a real site that is not in the site group already recorded on the account: `The preferred site ID must be contained in the given site group.` |
| `404` | Not found | The account does not exist, or is not fully set up: `User {username} cannot be found when calling UpdateUserPreferences`. Numeric-role tenants get this for every account. |
| `500` | Internal server error | `details` was omitted from the request body. Also returned when the change cannot be saved completely, or the account's record is no longer found at the moment of saving. Returned with no body. |