> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.

# update_user_attribute

> Rename a user attribute, change its key, options, default or whether statement exports carry it. Options are the whole list: a label left out is removed.

Rename a user attribute, change its key, its options, its default or whether
the statement exports carry it, and return it as it now stands.

Pass at least one of `name`, `key`, `options`, `default` or `exported` — a call
with none of them has nothing to update. Sending the values the attribute
already has changes nothing, so the same call can be sent twice.

`options` is the attribute's **whole** list, not an addition to it: read the
attribute's current options with
[`list_user_attributes`](https://docs.qobra.co/mcp_documentation/tools/list_user_attributes) first.
An option left out is removed and its value cleared from every person who held
it, as when an option is removed in the Qobra web app. An option cannot be
renamed here — a new label is a new option, and the people holding the old one
lose that value. Removing the option the default names also takes the default
off.

A new key changes how Qobra's public API and Excel imports address the
attribute. The scopes and statements reading the attribute follow a rename.

An attribute's type, description and uniqueness cannot be changed after it is
created. To change a person's value, use
[`update_user_attribute_values`](https://docs.qobra.co/mcp_documentation/tools/update_user_attribute_values).

The call is refused when:

* `key`, `options` or `default` is passed for an attribute synced from an
  integration, which takes them from the source.
* `default` is passed for a unique attribute: everyone created afterwards would
  start with the same value.
* `options` is passed for an attribute that is not a picklist or a
  multipicklist.
* the new key is already carried by another attribute, is one of the keys the
  public API serves every user under, or normalizes to nothing.
* `default` does not match the attribute's type or is not one of its options,
  or is an empty string on a bool attribute, whose default is always true or
  false.

Requires write permission on company settings > user attributes. Available only
where the Qobra write tools beta is enabled. Every write is recorded in the
audit trail as the `Qobra MCP` agent.

```json Example arguments theme={null}
{
  "attribute_id": "665f1c2e8a4b3d0012a7e9f1",
  "name": "Sales segment",
  "options": ["SMB", "Mid-Market", "Enterprise"],
  "default": "SMB",
  "exported": true
}
```

## Parameters

> **Body**
>
> **attribute\_id** `string` *required*
>
> Id of the attribute to update — the `id` list\_user\_attributes returns, or
> the one create\_user\_attribute just returned. Never a name or a key.
>
> **name** `string`
>
> New display name of the attribute. Omit to leave the current name as it
> is.
>
> **key** `string`
>
> New stable key of the attribute: the identifier the public API and an
> Excel import address it by. Lowercase and underscore-separated, and unique
> across the company's attributes; `id`, `email`, `status`, `name`, `role`,
> `currency` and `calculation_currency` are taken by the public API. Omit to
> leave the current key as it is.
>
> **options** `string[]`
>
> For a picklist or a multipicklist attribute, the complete list of the
> labels people choose from, in order — not only the new ones. A label
> already offered is kept, a new one is added, and one left out is removed,
> which clears it from every person holding it. Omit to leave the options as
> they are.
>
> **default** `string | number | boolean | string[]`
>
> The value people created from now on start with, typed to match the
> attribute: text for string, a number for float/amount/percentage,
> true/false for bool, an ISO date (`2026-03-14`) for date, one label out of
> the options for picklist, a list of labels for multipicklist. People
> already in Qobra keep their values. Pass an empty string to take the
> default off — except on a bool attribute, whose default is always true or
> false. Omit to leave the current default as it is.
>
> **exported** `boolean`
>
> Whether the attribute is a column of the statement exports — the only
> export it applies to: the users export always carries every attribute.
> Omit to leave it as it is.

## Response

> **Body**
>
> **attribute** `object`
>
> The attribute as it now stands, its active options included — the same row
> list\_user\_attributes returns.
>
> **object properties**
>
> **id** `string`
>
> **name** `string`
>
> **description** `string`
>
> What the company says this attribute means, in their own words. Null
> when they wrote none.
>
> **type** `string`
>
> One of: `float`, `amount`, `percentage`, `string`, `picklist`,
> `multipicklist`, `bool`, `date`, `user`.
>
> **options** `string[]`
>
> Selectable option labels for a picklist or multipicklist attribute, in
> definition order; null for every other type. Archived options are left
> out.
>
> **readonly** `boolean`
>
> True when the value cannot be edited in Qobra — it is owned by the
> source system that syncs it.
>
> **integration** `object`
>
> The company connection this attribute is synced from; null when it is
> maintained in Qobra itself.
>
> **object properties**
>
> **id** `string`
>
> **name** `string`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.