# Get specific user setting

> GET /v1/users/{id}/settings/{app}/{category}/{name} · Settings and configurations API

Source: https://developer.kustomer.com/api/settings-and-configurations/get-specific-user-setting

```http
GET https://{orgname}.api.kustomerapp.com/v1/users/{id}/settings/{app}/{category}/{name}
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: `org.permission.setting.read`, `org.permission.user.read`; or legacy `org.admin.setting.read`, `org.admin.user.read`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

Search settings for a specific user.

## About Settings

Settings are named configuration values that change how Kustomer and installed apps behave. Org settings apply to everyone in the org, such as satisfaction survey timing or an app's API key, while user settings are personal preferences, such as what the send button does for one agent.

Kustomer stores much of its configuration as settings: single values identified by three parts, `app`, `category` and `name`, written together as a path such as `kustomer.satisfaction.lockTime`. `app` is `kustomer` for built-in settings, or the app's name for settings declared by an installed [app](https://developer.kustomer.com/docs/apps/settings). The admin settings pages in Kustomer read and write many of these values, and apps use them to store per-org configuration such as an API key or a store domain. Each setting has a `type` (for example a string, number or boolean) and a default value, and `value` holds the current value.

#### Org settings and user settings

There are two separate sets of settings, and they don't inherit from each other:

| Scope | Applies to | Example | Paths |
| --- | --- | --- | --- |
| Org | Everyone in the org | `kustomer.satisfaction.lockTime` | `/v1/settings/...` |
| User | One user | `chat.outbound.sendAction` | `/v1/users/current/settings/...` and `/v1/users/{id}/settings/...` |

Org settings are things an admin decides for the whole org. User settings are personal preferences that each user sets in the agent desktop, such as an undo-send delay or a notification sound. A user setting is not an override of an org setting with the same name; each scope has its own list of settings.

You can only read and write settings that Kustomer or an installed app defines. You can't invent new names, and a path that doesn't match a defined setting returns `404`. A setting that has never been changed returns its default value.

#### Reading values

The list endpoints return every setting in scope, optionally narrowed with `app` and `category` (`category` accepts a comma-separated list). Use `fields` to choose which attributes come back, such as `name,value`. App settings of type `secret` are write-only: reading one returns a placeholder, never the real value.

#### Which endpoint to use

| To | Call |
| --- | --- |
| List org settings | [`GET /v1/settings`](https://developer.kustomer.com/api/settings-and-configurations/get-settings) |
| Read or change one org setting | [`GET`](https://developer.kustomer.com/api/settings-and-configurations/get-a-setting) or [`PUT /v1/settings/{app}/{category}/{name}`](https://developer.kustomer.com/api/settings-and-configurations/update-a-setting) |
| List the signed-in user's settings | [`GET /v1/users/current/settings`](https://developer.kustomer.com/api/settings-and-configurations/get-user-settings-for-current-user) |
| Read or change one of the signed-in user's settings | [`GET`](https://developer.kustomer.com/api/settings-and-configurations/get-specific-user-setting-for-current-user) or [`PUT /v1/users/current/settings/{app}/{category}/{name}`](https://developer.kustomer.com/api/settings-and-configurations/update-specific-user-setting-for-current-user) |
| List another user's settings, as an admin | [`GET /v1/users/{id}/settings`](https://developer.kustomer.com/api/settings-and-configurations/get-user-settings) |
| Read or change one of another user's settings, as an admin | [`GET`](https://developer.kustomer.com/api/settings-and-configurations/get-specific-user-setting) or [`PUT /v1/users/{id}/settings/{app}/{category}/{name}`](https://developer.kustomer.com/api/settings-and-configurations/update-specific-user-setting) |

To change a setting, send `{ "value": ... }` with a value of the setting's type, and the response returns the stored setting. Some settings also check the value itself, and reject an invalid one with `400`. Changing an org setting requires an admin role with permission to manage settings, and reading or changing another user's settings also requires permission to manage users. Any signed-in user can read and change their own user settings. For an API key, "current user" means the key's own user, so to change an agent's preferences from an integration, use the `/v1/users/{id}/settings` paths.

Related: [App settings](https://developer.kustomer.com/docs/apps/settings), [Users](https://developer.kustomer.com/api/access-management#users), [Notifications](https://developer.kustomer.com/api/settings-and-configurations#notifications)

### Recipes

#### 1. Change an org setting, checking its type first

Read a built-in setting's type and current value, then change it, for example to give customers longer to answer a satisfaction survey.

**Step 1.** [`GET /v1/settings`](https://developer.kustomer.com/api/settings-and-configurations/get-settings.md). List the settings in the category with `fields=name,value,type`, so you know the path, the current value and what kind of value to send. Keep the current value in case you need to undo the change. `kustomer.satisfaction.lockTime` is a number of milliseconds, 24 hours by default.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/settings?app=kustomer&category=satisfaction&fields=name,value,type" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/settings --query app=kustomer --query category=satisfaction \
  --query fields=name,value,type | jq -r '.data[] | [.id, .attributes.type, .attributes.value] | @tsv'
```

**Step 2.** [`PUT /v1/settings/{app}/{category}/{name}`](https://developer.kustomer.com/api/settings-and-configurations/update-a-setting.md). Send the new `value` with the setting's type: a JSON number here, not a string. This sets 48 hours. Values the setting doesn't allow, such as a `lockTime` under one hour, fail with `400`.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/settings/kustomer/satisfaction/lockTime" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"value": 172800000}'
```

```bash title="kusty"
kusty api PUT /v1/settings/kustomer/satisfaction/lockTime --field value:=172800000
```

> kusty's `--fields` flag only trims what kusty prints. To ask the API for fewer fields, pass `fields` as a query parameter, as above.

#### 2. Configure an installed app's settings from a script

Fill in an app's per-org configuration, such as an API key and a store domain, when you roll the app out to several orgs.

**Step 1.** [`GET /v1/settings`](https://developer.kustomer.com/api/settings-and-configurations/get-settings.md). List the settings the app defines, with their types. Each `id` is the path to write to; take the app part from here, because Kustomer can adjust a private app's name. Settings of type `secret` read back as `****`, so you can't use this to check their values.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/settings?app=$APP_NAME&fields=name,category,type,value" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/settings --query app=$APP_NAME --query fields=name,category,type,value \
  | jq -r '.data[] | [.id, .attributes.type, .attributes.value] | @tsv'
```

**Step 2.** [`PUT /v1/settings/{app}/{category}/{name}`](https://developer.kustomer.com/api/settings-and-configurations/update-a-setting.md). Set each value by its path. For a `secret`, the response shows `****` too, but the real value is stored for the app's server-side features to use. See [app settings](https://developer.kustomer.com/docs/apps/settings) for how an app declares and reads them.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/settings/$APP_NAME/default/apiKey" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"value\": \"$PARTNER_API_KEY\"}"
```

```bash title="kusty"
kusty api PUT /v1/settings/$APP_NAME/default/apiKey --field value="$PARTNER_API_KEY"
```

> Apps with one category usually call it `default`; use the category and name from the list. A path the app doesn't define returns `404`; you can't add settings this way.

#### 3. Set an agent's preference from an integration

Change one user's personal setting as an admin, for example what the chat send button does, when onboarding agents in bulk.

**Step 1.** [`GET /v1/users/{id}/settings`](https://developer.kustomer.com/api/settings-and-configurations/get-user-settings.md). Read the user's settings in the category. `chat.outbound.sendAction` is what the chat send button does: `send`, `sendAndMarkDone` or `sendAndSnooze`.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/users/$USER_ID/settings?app=chat&category=outbound" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/users/$USER_ID/settings --query app=chat --query category=outbound \
  | jq -r '.data[] | [.id, .attributes.value] | @tsv'
```

**Step 2.** [`PUT /v1/users/{id}/settings/{app}/{category}/{name}`](https://developer.kustomer.com/api/settings-and-configurations/update-specific-user-setting.md). Send the new `value`. This needs permission to manage both settings and users. The response's `relationships.user` is the user you changed.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/users/$USER_ID/settings/chat/outbound/sendAction" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"value": "sendAndMarkDone"}'
```

```bash title="kusty"
kusty api PUT /v1/users/$USER_ID/settings/chat/outbound/sendAction --field value=sendAndMarkDone
```

> Use the `/v1/users/{id}/settings` paths from an integration. With an API key, `/v1/users/current/settings` changes the key's own user, not an agent's.

### Example object

A real record from [`GET /v1/settings`](https://developer.kustomer.com/api/settings-and-configurations/get-settings.md):

```json
{
  "id": "kustomer.satisfaction.lockTime",
  "type": "setting",
  "attributes": {
    "name": "lockTime",
    "value": 86400000,
    "app": "kustomer",
    "category": "satisfaction"
  },
  "relationships": {
    "org": {
      "links": {
        "self": "/v1/orgs/57504f64d76808100089eb44"
      },
      "data": {
        "type": "org",
        "id": "57504f64d76808100089eb44"
      }
    }
  }
}
```

Fields:

- `id` (string): The setting's full path, `app.category.name`, made of the same three parts as its URL.
- `attributes.name` (string): The last part of the path, unique within its app and category.
- `attributes.value` (number): The current value, or the default if nobody has changed it. Its type depends on the setting; this one is in milliseconds (24 hours). App settings of type `secret` read back as `****`.
- `attributes.app` (string): `kustomer` for built-in settings, or the name of the installed app that defines the setting.
- `attributes.category` (string): A group of related settings, such as `satisfaction`. The list endpoints' `category` filter takes several, comma-separated.

### Relationships

- Points to **Users** via `relationships.user`: For user settings, the user whose preference a setting is. Org settings belong to the whole org and have no user.

### Permissions

Fewest roles for a read-only integration: `org.permission.setting.read`. For every endpoint: `org.permission.setting.read`, `org.permission.setting.update`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | User ID. |
| `app` | string | yes | Application identifier. |
| `category` | string | yes | Setting category. |
| `name` | string | yes | Setting key name. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | string | no | Comma-separated setting fields to include in the response. Supported fields are `name`, `value`, `app`, `appVersion`, `type`, `description`, `hidden`, `category`, `createdAt`, `modifiedBy`, `modifiedAt`, `updatedAt`, `org`, and `user`; unknown fields are ignored. |

## Responses

### 200

OK

- `data` (object, required)
  - `id` (string, required)
  - `type` (string, required)
  - `attributes` (object, required)
    - `name` (string, required)
    - `value` (string, required)
    - `app` (string, required)
    - `type` (string, required)
    - `category` (string, required)
    - `createdAt` (string, required)
    - `updatedAt` (string, required)
  - `relationships` (object, required)
    - `org` (object, required)
    - `user` (object, required)

```json
{
  "data": {
    "id": "chat.notifications.messageCreateSound",
    "type": "setting",
    "attributes": {
      "name": "messageCreateSound",
      "value": null
    }
  }
}
```

### 400

Bad Request

### 401

Unauthorized

### 403

Forbidden

### 404

Not Found

## Example request

```bash
curl --request GET \
  --url 'https://api.kustomerapp.com/v1/users/5e15fa45623f88001a8e0bbb/settings/kustomer/conversation/defaultView' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```