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

# The Custom Attribute Definition object

> The schema behind your organization's custom fields on users, how to find one, and the configs that feed it.

A custom attribute definition is the schema of one extra field your organization keeps on users,
such as "Cost Center", "Department", or "Data Classification". It describes the field, not any
particular value of it. v1 lists only the custom attributes on users, and doesn't list multi-select
attributes.

Values live on the users the field is attached to. A [user](https://docs.lumos.com/reference/v1/objects/user.md) returns its
custom attribute values under `custom_attributes` when you expand them.
[List Custom Attribute Definitions](https://docs.lumos.com/api-reference/v1/custom-attribute-definitions/list-custom-attribute-definitions.md)
tells you what those keys mean, what type each one holds, and where it came from.

```json The Custom Attribute Definition object theme={null}
{
  "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "label": "Cost Center",
  "name": "costCenter",
  "attribute_type": "string",
  "config_type": "user",
  "source_type": "synced"
}
```

## Attributes

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier for the definition. Always present. |
| `label` | string | The attribute's display name, unique in your organization. Always present. |
| `name` | string or null | The attribute's name in one of the systems it comes from. |
| `attribute_type` | string | The value type. One of `string`, `boolean`, `integer`, `datetime`, `json`, `user`, `group`, or `single-select`. |
| `config_type` | string | The entity the attribute attaches to. Always `user`. |
| `source_type` | string | Where the definition comes from: `synced`, `native`, or `ai-generated`. |

## Identifying a definition

`id` identifies a definition, and
[Get Custom Attribute Definition](https://docs.lumos.com/api-reference/v1/custom-attribute-definitions/get-custom-attribute-definition.md)
reads one by it. `label` is unique too. It's what keys the `custom_attributes` map on a user, and
what you filter the list on.

One label returns one definition, even when several apps feed it. For example, `?label=Department` returns a single unified definition, not a list of near-duplicates:

```bash theme={null}
curl -s 'https://api.lumos.com/v1/custom-attribute-definitions?label=Department' \
  --header 'Authorization: Bearer lsk_your_token'
```

`name` comes from one source. Where several sources feed one label, `name` reflects one of them,
so treat it as a hint about the upstream field rather than an authoritative mapping.
[Configs](#configs) gives each source's own name.

## Configs

Each app that syncs the attribute adds a config to its definition, and so does a native attribute
your team defines in Lumos.
[List Custom Attribute Definition Configs](https://docs.lumos.com/api-reference/v1/custom-attribute-definitions/list-custom-attribute-definition-configs.md)
lists a definition's configs, highest priority first:

| Field | Type | Description |
| - | - | - |
| `name` | string | The attribute's name in this source. Always present. |
| `app_id` | string or null | The [app](https://docs.lumos.com/reference/v1/objects/app.md) the config belongs to. `null` when it has none, or when its app no longer exists. |
| `priority` | integer | The config's rank. `0` is highest. Configs that tie all contribute values. Always present. |
| `attribute_type` | string | The type of value this config holds. Always present. |
| `source_type` | string | Where this config comes from: `synced`, `native`, or `ai-generated`. Always present. |

## Filtering

Five filters narrow the list, and you can combine them:

| Filter | Effect |
| - | - |
| `label` | Returns the single unified definition for this exact label. Not a search. |
| `config_type` | `user` returns every definition. It's the only value. |
| `source_type` | Only `synced`, `native`, or `ai-generated` definitions. |
| `attribute_type` | Only definitions holding a given value type. |
| `app_id` | Only definitions sourced from one app. |

`label` matches exactly rather than searching, so a partial label returns nothing rather than a
shortlist.

`config_type`, `source_type`, and `attribute_type` take the values in [Attributes](#attributes).
Any other value, such as `SINGLESELECT` or `multi-select`, returns `400`.

## Managing definitions

v1 reads definitions and their configs, but can't create or change them. Manage definitions in the
Lumos UI.

## Endpoints

| Endpoint | Path |
| - | - |
| [List Custom Attribute Definitions](https://docs.lumos.com/api-reference/v1/custom-attribute-definitions/list-custom-attribute-definitions.md) | `GET /v1/custom-attribute-definitions` |
| [Get Custom Attribute Definition](https://docs.lumos.com/api-reference/v1/custom-attribute-definitions/get-custom-attribute-definition.md) | `GET /v1/custom-attribute-definitions/{definition_id}` |
| [List Custom Attribute Definition Configs](https://docs.lumos.com/api-reference/v1/custom-attribute-definitions/list-custom-attribute-definition-configs.md) | `GET /v1/custom-attribute-definitions/{definition_id}/configs` |