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

# Update a user attribute definition

`PUT /api/v1/user-attributes/{id}`

Updates a custom user attribute definition. Omitted fields keep their current values. The type cannot change, and a multi-valued attribute cannot be changed back to a single value. Requires the Manage User Attributes permission.

## Path parameters

- `id` string, uuid, required — User attribute definition ID

## Request body

- UserAttributesUpdateBody
  - `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, so 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 one, and a list member that trims to empty is rejected.
    - string
    - number
    - union[]
      - union
        - string
        - number
  - `description` string, nullable — Human-readable description of the attribute and its purpose. An empty string is stored as null.
  - `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_".

## Response `200`

User attribute definition updated

- UserAttributesUpdateResponse
  - `default_value` union, required — Default value applied when no user-specific value is set. When multiple_values is true, this is an array. Null if no default is configured.
    - string
    - number
    - union[]
      - union
        - string
        - number
  - `description` string, nullable, required — Human-readable description of the attribute and its purpose
  - `id` string, required — Unique identifier for custom attributes. Empty string for system-defined attributes.
  - `label` string, required — Display name shown in the Omni UI
  - `multiple_values` boolean, required — Whether the attribute accepts an array of values. When true, default_value and user-specific values are arrays.
  - `name` string, required — Reference name used in model SQL and in embed SSO URL parameters
  - `system` boolean, required — System-defined attributes (e.g. omni_user_id, omni_user_email) are built-in and read-only. Custom attributes have system=false.
  - `type` 'String' | 'Number', required — Data type that determines valid values. String attributes accept text, Number attributes accept numeric values stored as strings for precision.

## Other responses

- `400` — Invalid request body or definition ID
- `401` — Authentication required
- `403` — Requires the Manage User Attributes permission
- `404` — User attribute definition does not exist
- `405` — Method not allowed
- `409` — Another user attribute definition already has this name or label, or the definition changed while it was being updated

## Changes

- **2026-09-22** `d3c0855161b1` — 1 info
  - endpoint added

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

---

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