The Custom Attribute Definition object

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 returns its custom attribute values under custom_attributes when you expand them. List Custom Attribute Definitions tells you what those keys mean, what type each one holds, and where it came from.

{
  "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 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:

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 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 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 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. 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	`GET /v1/custom-attribute-definitions`
Get Custom Attribute Definition	`GET /v1/custom-attribute-definitions/{definition_id}`
List Custom Attribute Definition Configs	`GET /v1/custom-attribute-definitions/{definition_id}/configs`

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

The Custom Attribute Definition object

Attributes

Identifying a definition

Configs

Filtering

Managing definitions

Endpoints

​Attributes

​Identifying a definition

​Configs

​Filtering

​Managing definitions

​Endpoints

Attributes

Identifying a definition

Configs

Filtering

Managing definitions

Endpoints