Get Started With Employee Attributes

What Are Employee Attributes?

The employee data model in the Lucca API is spread across several resources: employee, employment, job-position, and their respective extension resources. In practice, a single piece of information about an employee — say, their manager, or a custom “T-shirt size” field — may live in any of these resources. Employee attributes provide a single, uniform endpoint to read any property from any of these resources, regardless of where it is stored. An employee-attribute is the value of one specific property for one specific employee. Each attribute is described by an employee-attribute-definition, which declares what the property is, what type it carries, and which resource it targets (employee, employment, or job-position).

Employee attributes are read-only. To update an employee’s data, use the dedicated write endpoints of the underlying resources (e.g. PATCH /lucca-api/employees/{id}).

Key Concepts

Definitions vs. Values

The employee-attribute merges both the attributes of primary resources (e.g. employee.givenName, job-position.manager) and custom extension properties (e.g. employment.e_tShirtSize) into a single uniform model. To achieve this, it relies on two distinct concepts:

employee-attribute-definition

Describes a property: its id, human-readable name, the JSON schema of its value, and the targetType (employee, employment, or job-position) it comes from. Definitions are defined by Lucca (for built-in properties) or by your organization (for custom extension properties).

employee-attribute

The actual value of a definition for a given employee. Contains the value itself, a reference to its definition, the employee it belongs to, and an applicability window indicating the date range over which this value is valid.

Applicability

Because many attributes come from time-bounded resources like employment or job-position, each employee-attribute exposes an applicability window:

"applicability": {
    "start": "2022-03-01",
    "end": "2024-11-30"
}

start is the inclusive lower bound. null means “since the beginning of time”.
end is the inclusive upper bound. null means “until the end of time”.
For attributes without a temporal dimension (e.g. employee.givenName, custom extensions), both bounds are null, meaning the value applies indefinitely.

Use the ?applicability.asOf={date} query parameter to filter attributes to those valid on a specific date — for example, to retrieve the state of an employee on their first day.

Multiple Values

Some definitions support multiple values per primary resource (e.g. “employee’s children”, where the same employee may have several entries). The multipleValueHandling property on the definition describes this behavior:

null → single-valued: at most one attribute per employee for this definition.
non-null → multi-valued: multiple attributes per employee are allowed, with a sorting direction and optional sortingProperty to order them.

Required OAuth Scopes

Scope	Access
`employee-attribute-definitions.readonly`	Read attribute definitions.
`employee-attribute-definitions.readwrite`	Read, create, update, and delete attribute definitions.
`employee-attributes.readonly`	Read attribute values.
`employee-attributes.readwrite`	Read, create, update, and delete attribute values.

For most read-only integration scenarios, the employee-attributes.readonly scope is sufficient. You only need employee-attribute-definitions.readonly if your integration needs to dynamically discover which attributes are available.

Access Rights

Beyond OAuth scopes, two additional constraints apply when reading employee attributes:

Business establishments: you may only access attributes of employees whose applicable business establishment is accessible to your client application.
Directory sections: each attribute definition is associated with an employee directory section. You may only access attributes belonging to sections that are accessible to your client application.

Common Workflows

1. Discover Available Definitions

Before reading values, you may want to discover which attribute definitions exist on the account.

GET /lucca-api/employee-attribute-definitions?sort=name HTTP/1.1
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: 2024-11-01
Accept: application/json

You can narrow results with these query parameters:

Parameter	Description
`id`	Filter by one or more definition IDs (comma-separated, max 100).
`search`	Find definitions whose name starts with the given string.
`isArchived`	Filter by archival status.
`sort`	Sort by `id`, `name`, or `createdAt` (prefix with `-` to reverse).

A definition response looks like this:

{
    "id": "e_tShirtSize",
    "type": "employee-attribute-definition",
    "url": "https://example.ilucca.net/lucca-api/employee-attribute-definitions/e_tShirtSize",
    "name": "T-shirt size",
    "targetType": "employee",
    "multipleValueHandling": null,
    "schema": {
        "$id": "/lucca-api/schemas/taxonomy-label-reference",
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "title": "taxonomy-label-reference",
        "description": "JSON representation of a reference to a taxonomy label",
        "type": ["object", "null"],
        "additionalProperties": false,
        "required": ["id"],
        "properties": {
            "id": {
                "type": "string",
                "minLength": 1
            },
            "type": {
                "type": "string",
                "const": "taxonomy-label",
                "readOnly": true
            },
            "url": {
                "type": "string",
                "format": "uri",
                "readOnly": true
            }
        }
    },
    "taxonomy": {
        "id": "45",
        "type": "taxonomy",
        "url": "https://example.ilucca.net/lucca-api/taxonomies/45"
    },
    "t9n": {
        "name": { "fr-FR": "Taille de t-shirt" }
    },
    "isArchived": false
}

The targetType tells you which underlying resource the value comes from:

`targetType`	Source resource
`employee`	`employee` or its extensions
`employment`	`employment` or its extensions
`job-position`	`job-position` or its extensions

2. Read Attributes for a Specific Employee

To fetch all current attribute values for a given employee, filter by employee.id and supply an applicability.asOf date:

GET /lucca-api/employee-attributes?employee.id=416&applicability.asOf=2026-03-24 HTTP/1.1
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: 2024-11-01
Accept: application/json

Query parameter	Description
`employee.id`	Filter by employee ID(s) (comma-separated, max 100).
`definition.id`	Filter by definition ID(s) — useful when you only need specific fields.
`applicability.asOf`	Only return attributes whose applicability window includes this date.
`value`	Filter by value. Supports dot-notation for object schemas (e.g. `value.e_childGivenName=John`).
`sort`	Sort by `id`, `createdAt`, `value`, or `definition.id`.

A response item looks like this:

{
    "id": "34879",
    "type": "employee-attribute",
    "url": "https://example.ilucca.net/lucca-api/employee-attributes/34879",
    "definition": {
        "id": "givenName",
        "type": "employee-attribute-definition",
        "url": "https://example.ilucca.net/lucca-api/employee-attribute-definitions/givenName"
    },
    "employee": {
        "id": "416",
        "type": "employee",
        "url": "https://example.ilucca.net/lucca-api/employees/416"
    },
    "applicability": null,
    "value": "John",
    "createdAt": "2014-04-12T09:43:52.432Z",
    "lastUpdatedAt": "2014-04-12T09:43:52.432Z"
}

3. Filtering on `value`

The value query parameter lets you filter attributes by their actual value. For scalar values (strings, booleans, numbers), pass the value directly:

# All employees whose job title is "Software Engineer"
GET /lucca-api/employee-attributes?definition.id=jobPosition.jobTitle&value=Software Engineer HTTP/1.1

For object-typed attributes (i.e. definitions whose schema.type is "object"), use dot-notation to filter on a specific sub-property of the value:

# All "children" attributes where the child's given name is "Alice"
GET /lucca-api/employee-attributes?definition.id=e_children&value.e_childGivenName=Alice HTTP/1.1

Filtering on value performs a strict equality check. Partial matches and range filters are not supported on this parameter.

4. Read a Single Attribute

When you already know the attribute’s id, retrieve it directly:

GET /lucca-api/employee-attributes/{id} HTTP/1.1
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: 2024-11-01
Accept: application/json

Understanding the `value` Property

The value type depends on the schema declared on the associated definition. Below are the most common schemas and their corresponding JSON representations:

Schema `$id`	JSON type of `value`	Example
`/lucca-api/schemas/short-text`	`string \| null`	`"Software Engineer"`
`/lucca-api/schemas/long-text`	`string \| null`	`"Lorem ipsum..."`
`/lucca-api/schemas/boolean`	`boolean \| null`	`true`
`/lucca-api/schemas/int32`	`number \| null`	`42`
`/lucca-api/schemas/decimal`	`number \| null`	`1.5`
`/lucca-api/schemas/legacy-date`	`string \| null`	`"2025-01-01T00:00:00"`
`/lucca-api/schemas/email`	`string \| null`	`"jdoe@example.org"`
`/lucca-api/schemas/employee-reference`	`object \| null`	`{"id": "416", "type": "employee", ...}`
`/lucca-api/schemas/taxonomy-label-reference`	`object \| null`	`{"id": "545", "type": "taxonomy-label", ...}`

For object-typed schemas, the value is a JSON object whose properties each follow their own referenced schema. Use the definition’s propertyDescriptions to discover and label each sub-property.

All schemas are nullable — a null value means the attribute has no value set for this employee.

Example: Multi-valued Object Attribute (Children)

This example walks through a custom attribute representing an employee’s dependent children. Because an employee may have several children, the definition uses multipleValueHandling to allow multiple values and declare how they should be sorted.

The Definition

{
    "id": "e_children",
    "type": "employee-attribute-definition",
    "url": "https://example.ilucca.net/lucca-api/employee-attribute-definitions/e_children",
    "name": "Children",
    "targetType": "employee",
    "multipleValueHandling": {
        "sorting": "ascending",
        "sortingProperty": "e_childBirthDate"
    },
    "schema": {
        "type": "object",
        "properties": {
            "e_childGivenName": {
                "$ref": "/lucca-api/schemas/short-text"
            },
            "e_childFamilyName": {
                "$ref": "/lucca-api/schemas/short-text"
            },
            "e_childBirthDate": {
                "$ref": "/lucca-api/schemas/legacy-date"
            }
        }
    },
    "propertyDescriptions": {
        "e_childGivenName": {
            "name": "Given Name",
            "taxonomy": null,
            "sortOrder": 0,
            "t9n": {
                "name": {
                    "en-US": "First Name",
                    "fr-FR": "Prénom"
                }
            }
        },
        "e_childFamilyName": {
            "name": "Family Name",
            "taxonomy": null,
            "sortOrder": 1,
            "t9n": {
                "name": {
                    "en-US": "Last Name",
                    "fr-FR": "Nom de famille"
                }
            }
        },
        "e_childBirthDate": {
            "name": "Birth Date",
            "taxonomy": null,
            "sortOrder": 2,
            "t9n": {
                "name": {
                    "fr-FR": "Date de naissance"
                }
            }
        }
    },
    "taxonomy": null,
    "isArchived": false,
    "t9n": {
        "name": {
            "fr-FR": "Enfants à charge"
        }
    }
}

Key points about this definition:

multipleValueHandling is non-null — multiple employee-attribute records can exist for the same employee under this definition (one per child).
sortingProperty: "e_childBirthDate" — clients should display children sorted by their birth date in ascending order.
propertyDescriptions — provides human-readable labels and translation keys for each object property, useful when building a UI.

The Corresponding Attributes

Querying GET /lucca-api/employee-attributes?employee.id=416&definition.id=e_children returns one item per child:

{
    "type": "employee-attributes",
    "url": "https://example.ilucca.net/lucca-api/employee-attributes?employee.id=416&definition.id=e_children",
    "items": [
        {
            "id": "87601",
            "type": "employee-attribute",
            "url": "https://example.ilucca.net/lucca-api/employee-attributes/87601",
            "definition": {
                "id": "e_children",
                "type": "employee-attribute-definition",
                "url": "https://example.ilucca.net/lucca-api/employee-attribute-definitions/e_children"
            },
            "employee": {
                "id": "416",
                "type": "employee",
                "url": "https://example.ilucca.net/lucca-api/employees/416"
            },
            "applicability": null,
            "value": {
                "e_childGivenName": "Alice",
                "e_childFamilyName": "Doe",
                "e_childBirthDate": "2015-06-12T00:00:00"
            },
            "createdAt": "2021-09-01T08:00:00.000Z",
            "lastUpdatedAt": "2021-09-01T08:00:00.000Z"
        },
        {
            "id": "87602",
            "type": "employee-attribute",
            "url": "https://example.ilucca.net/lucca-api/employee-attributes/87602",
            "definition": {
                "id": "e_children",
                "type": "employee-attribute-definition",
                "url": "https://example.ilucca.net/lucca-api/employee-attribute-definitions/e_children"
            },
            "employee": {
                "id": "416",
                "type": "employee",
                "url": "https://example.ilucca.net/lucca-api/employees/416"
            },
            "applicability": null,
            "value": {
                "e_childGivenName": "Bob",
                "e_childFamilyName": "Doe",
                "e_childBirthDate": "2018-03-22T00:00:00"
            },
            "createdAt": "2021-09-01T08:00:00.000Z",
            "lastUpdatedAt": "2021-09-01T08:00:00.000Z"
        }
    ]
}

Because applicability is null on both items, this attribute has no temporal dimension — the employee’s children list is not tied to an employment or job-position period. Use ?sort=value.e_childBirthDate to retrieve them already sorted by birth date, matching the sortingProperty declared on the definition.

Paginating Results

Like all collection endpoints, /lucca-api/employee-attributes is paginated. Use ?include=totalCount,links to get the total count and cursor links for navigating pages. The default and maximum page size is defined in the API Reference.

GET /lucca-api/employee-attributes?employee.id=416&applicability.asOf=2026-03-24&include=totalCount,links&limit=50 HTTP/1.1
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: 2024-11-01

Pagination

Learn how cursor-based pagination works.

Filtering

Learn more about filtering collections.

Overview

Files

Organization

Employee Records

Events & Webhooks

Get Started With Employee Attributes

What Are Employee Attributes?

Key Concepts

Definitions vs. Values

employee-attribute-definition

employee-attribute

Applicability

Multiple Values

Required OAuth Scopes

Access Rights

Common Workflows

1. Discover Available Definitions

2. Read Attributes for a Specific Employee

3. Filtering on `value`

4. Read a Single Attribute

Understanding the `value` Property

Example: Multi-valued Object Attribute (Children)

The Definition

The Corresponding Attributes

Paginating Results

Pagination

Filtering

Overview

Files

Organization

Employee Records

Events & Webhooks

​What Are Employee Attributes?

​Key Concepts

​Definitions vs. Values

employee-attribute-definition

employee-attribute

​Applicability

​Multiple Values

​Required OAuth Scopes

​Access Rights

​Common Workflows

​1. Discover Available Definitions

​2. Read Attributes for a Specific Employee

​3. Filtering on value

​4. Read a Single Attribute

​Understanding the value Property

​Example: Multi-valued Object Attribute (Children)

​The Definition

​The Corresponding Attributes

​Paginating Results

Pagination

Filtering

What Are Employee Attributes?

Key Concepts

Definitions vs. Values

Applicability

Multiple Values

Required OAuth Scopes

Access Rights

Common Workflows

1. Discover Available Definitions

2. Read Attributes for a Specific Employee

3. Filtering on `value`

4. Read a Single Attribute

Understanding the `value` Property

Example: Multi-valued Object Attribute (Children)

The Definition

The Corresponding Attributes

Paginating Results