Get settings
/v1/settingsorg.permission.setting.readorg.user.setting.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Search settings.
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. 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 |
| Read or change one org setting | GET or PUT /v1/settings/{app}/{category}/{name} |
| List the signed-in user's settings | GET /v1/users/current/settings |
| Read or change one of the signed-in user's settings | GET or PUT /v1/users/current/settings/{app}/{category}/{name} |
| List another user's settings, as an admin | GET /v1/users/{id}/settings |
| Read or change one of another user's settings, as an admin | GET or PUT /v1/users/{id}/settings/{app}/{category}/{name} |
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.
Query parameters
Exact setting application identifier to filter by. Values are dynamic and depend on the setting definitions for the org/apps.
"kustomer"Exact setting category to filter by. Values are dynamic and depend on the setting definitions for the selected app.
"conversation"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.
"name,value,type"Responses
OK