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

# Get Started With Taxonomies

> Learn what taxonomies are and how to list available values for custom properties.

## 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`:

```json theme={null}
{
    "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:

```http theme={null}
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:

```json theme={null}
{
    "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
        }
    ]
}
```

<Tip>Use `isArchived=false` to exclude deprecated values that are no longer selectable.</Tip>

***

## Required Scope

Reading taxonomies and taxonomy-labels requires the `taxonomies.readonly` scope (or `taxonomies.readwrite`).

***

## Filtering and Sorting Taxonomy-Labels

| Parameter     | Description                                                        |
| :------------ | :----------------------------------------------------------------- |
| `taxonomy.id` | Filter labels by taxonomy (required in most use cases).            |
| `isArchived`  | Filter by archival status (`true`, `false`).                       |
| `search`      | Find labels whose name starts with the given string.               |
| `sort`        | Sort by `id`, `name`, or `createdAt` (prefix with `-` to reverse). |

***

## Summary

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