Skip to main content

​
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: 
{
    "id": "e_tShirtSize",
    "name": "T-shirt size",
    "schema": {
        "$id": "/lucca-api/schemas/taxonomy-label-reference",
        ...
    },
    "taxonomy": {
        "id": "45",
        "type": "taxonomy",
        "url": "https://example.ilucca.net/lucca-api/taxonomies/45"
    }
}
The taxonomy.id field tells you which taxonomy holds the allowed values. To retrieve them, call: 
GET /lucca-api/taxonomy-labels?taxonomy.id=45&limit=100 HTTP/1.1
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: 2024-11-01
Accept: application/json
The response lists all labels in that taxonomy: 
{
    "items": [
        {
            "id": "101",
            "type": "taxonomy-label",
            "url": "https://example.ilucca.net/lucca-api/taxonomy-labels/101",
            "name": "Small",
            "taxonomy": { "id": "45", "type": "taxonomy" },
            "isArchived": false
        },
        {
            "id": "102",
            "type": "taxonomy-label",
            "url": "https://example.ilucca.net/lucca-api/taxonomy-labels/102",
            "name": "Medium",
            "taxonomy": { "id": "45", "type": "taxonomy" },
            "isArchived": false
        },
        {
            "id": "103",
            "type": "taxonomy-label",
            "url": "https://example.ilucca.net/lucca-api/taxonomy-labels/103",
            "name": "Large",
            "taxonomy": { "id": "45", "type": "taxonomy" },
            "isArchived": false
        }
    ]
}
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

ParameterDescription
taxonomy.idFilter labels by taxonomy (required in most use cases).
isArchivedFilter by archival status (true, false).
searchFind labels whose name starts with the given string.
sortSort by id, name, or createdAt (prefix with - to reverse).

​
Summary

StepAction
1Read the employee-attribute-definition to find taxonomy.id
2Call GET /lucca-api/taxonomy-labels?taxonomy.id={id} to list available values
3Use the label id when writing an employee-attribute value