# 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`)

HTML version: [Creates or updates a user preference for the currently logged-in user](https://support.gladstonesoftware.cloud/reference/users/creates-or-updates-a-user-preference-for-the-currently-logged-in-user)

## 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](updates-user-preferences-and-application-settings-for-a-specific-user.md), 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](updates-the-details-and-settings-for-a-specific-administrative-user.md) 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](../../guides/authenticating-with-gladstone-apis.md).

## 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](retrieves-a-specific-user-preference-for-the-currently-logged-in-user.md). 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](deletes-a-specific-user-preference-for-the-currently-logged-in-user.md). Exceeding 4000 characters is not validated up front and surfaces as a `500`. |

## Sample request

```bash title="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

```json title="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. |