---
title: "Create a user attribute definition"
method: POST
path: "/api/v1/user-attributes"
tags: ["User Attributes"]
---

# Create a user attribute definition

`POST /api/v1/user-attributes`

Creates a custom user attribute definition. Requires the Manage User Attributes permission. The name must be unique within the organization; the label must be unique among the custom attributes and may match the label of a system attribute. Names must not start with "omni_", labels must not start with "Omni", and the reserved connection labels are rejected.

## Request body

- UserAttributesCreateBody
  - `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, 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 — Whether the attribute accepts an array of values. Defaults to false.
  - `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_".
  - `type` 'String' | 'Number', required — Data type that determines valid values. String attributes accept text, Number attributes accept numeric values stored as strings for precision.

## Response `201`

User attribute definition created

- UserAttributesCreateResponse
  - `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
- `401` — Authentication required
- `403` — Requires the Manage User Attributes permission
- `405` — Method not allowed
- `409` — A user attribute definition with this name or label already exists

## Changes

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

[Change history](https://skmtc.dev/omniapp/apis/omni-api/changes/api/v1/user-attributes/post.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)