What Are Taxonomies?
A taxonomy is a named list of values that can be used by custom properties. Think of it as a configurable picklist: “T-shirt sizes”, “Office locations”, etc.
Each individual entry in a taxonomy is called a taxonomy-label (e.g. “Small”, “Medium”, “Large” within a “T-shirt sizes” taxonomy).
When a custom property is of type taxonomy-label-reference, its value must be one of the labels belonging to a specific taxonomy.
Common Use Case: Listing Available Values for a Custom Employee Attribute
When reading employee attributes, you may encounter a definition whose schema is taxonomy-label-reference:
The taxonomy.id field tells you which taxonomy holds the allowed values. To retrieve them, call:
The response lists all labels in that taxonomy:
Use isArchived=false to exclude deprecated values that are no longer selectable.
Required Scope
Reading taxonomies and taxonomy-labels requires the taxonomies.readonly scope (or taxonomies.readwrite).
Filtering and Sorting Taxonomy-Labels
Summary
