---
title: "Update a user attribute definition"
method: PUT
path: "/v1/user-attributes/{userAttributeId}"
tags: ["User attributes"]
---

# Update a user attribute definition

`PUT /v1/user-attributes/{userAttributeId}`

## Request

- Base URL: `https://blobsrus.omniapp.co/api`
- URL: `https://blobsrus.omniapp.co/api/v1/user-attributes/{userAttributeId}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

<Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

Update a custom [user attribute](/administration/users/attributes) definition. Omitted fields keep their current values. The attribute's `type` cannot change, and a multiple-values attribute cannot be changed back to a single value.

## Path parameters

- `userAttributeId` string, uuid, required

## Request body

- UserAttributeObject
  - `default_value` union: Default value applied when no user-specific value is set. A single value when `multiple_values` is `false`, an array when it is `true`. Strings are trimmed. Number attributes accept numbers or numeric strings and store them as strings. Numbers are converted to strings on receipt; send anything beyond the JSON safe integer range (`2^53 - 1`) as a string or it loses precision before Omni sees it. Null or a string that trims to empty means no default. An empty array clears the default of a multi-valued attribute and is rejected for a single-valued attribute. A list member that trims to empty is rejected.
    - string
    - number
    - union[]
      - union
        - string
        - number
  - `description` string: Human-readable description of the attribute and its purpose. An empty string is stored as null.
  - `id` string: Unique identifier for custom attributes. Empty string for system-defined attributes.
  - `label` string: Display name shown in the Omni UI. Unique among the custom attributes in the organization, and may match the label of a system attribute. Must not start with `Omni` and must not be one of the reserved connection labels: `Host`, `Password`, `Database`, `Port`, `Schema`, `Connection Name`.
  - `multiple_values` boolean: Whether the attribute accepts an array of values.
  - `name` string: Reference name used in model SQL and in embed SSO URL parameters. Unique within the organization. Must start with a letter, contain only letters, numbers and underscores, and must not start with `omni_`.
  - `system` boolean: System-defined attributes (e.g. `omni_user_id`, `omni_user_email`) are built-in and read-only. Custom attributes have a `false` value.
  - `type` 'String' | 'Number': Data type that determines valid values. `String` attributes accept text, `Number` attributes accept numeric values stored as strings for precision. Immutable after creation.

## Response `200`

User attribute definition updated

- object
  - `default_value` union, required: Default value applied when no user-specific value is set. A single value when `multiple_values` is `false`, an array when it is `true`. Strings are trimmed. Number attributes accept numbers or numeric strings and store them as strings. Numbers are converted to strings on receipt; send anything beyond the JSON safe integer range (`2^53 - 1`) as a string or it loses precision before Omni sees it. Null or a string that trims to empty means no default. An empty array clears the default of a multi-valued attribute and is rejected for a single-valued attribute. A list member that trims to empty is rejected.
    - string
    - number
    - union[]
      - union
        - string
        - number
  - `description` string, required: Human-readable description of the attribute and its purpose. An empty string is stored as null.
  - `id` string, required: Unique identifier for custom attributes. Empty string for system-defined attributes.
  - `label` string, required: Display name shown in the Omni UI. Unique among the custom attributes in the organization, and may match the label of a system attribute. Must not start with `Omni` and must not be one of the reserved connection labels: `Host`, `Password`, `Database`, `Port`, `Schema`, `Connection Name`.
  - `multiple_values` boolean, required: Whether the attribute accepts an array of values.
  - `name` string, required: Reference name used in model SQL and in embed SSO URL parameters. Unique within the organization. Must start with a letter, contain only letters, numbers and underscores, and must not start with `omni_`.
  - `system` boolean, required: System-defined attributes (e.g. `omni_user_id`, `omni_user_email`) are built-in and read-only. Custom attributes have a `false` value.
  - `type` 'String' | 'Number', required: Data type that determines valid values. `String` attributes accept text, `Number` attributes accept numeric values stored as strings for precision. Immutable after creation.

## Other responses

- `400`: Bad Request. The request body or the `userAttributeId` parameter failed validation.
- `401`: Authentication required
- `403`: Forbidden. Requires Organization Admin permissions.
- `404`: Not Found. No user attribute definition with that ID exists in the caller's organization.
- `405`: Method Not Allowed - Invalid HTTP method for this endpoint
- `409`: Conflict. Another user attribute definition already has this name or label, or the definition changed while it was being updated.
- `429`: Too Many Requests - Rate limit exceeded (60 requests/minute)

## Changes

- **2026-11-03** `43290040f88f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/omni/apis/omni-api/changes/v1/user-attributes/:userAttributeId/put.md)

---

[API](https://skmtc.dev/omni/apis/omni-api.md) - [All operations](https://skmtc.dev/omni/apis/omni-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omni/apis/omni-api/revisions/43290040f88f?raw)