Skip to main content

​
What Are Employee Attributes?

The employee data model in the Lucca API is spread across several primary resources: employee, employee-personal-record, employment, and job-position. Each carries a set of system properties defined by Lucca (e.g. employee.givenName, personal.legalGender, jobPosition.manager). In addition, any of these primary resources can be extended with extension properties (e.g. a “T-shirt size” field), whether your organization created them to fit its needs or a Lucca application added them. In practice, this means a single piece of information about an employee may live on any of these resources, as either a system or an extension property. Employee attributes provide a single, uniform endpoint to access any property — system or extension — from any primary API resource, 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, which primary resource it targets (targetType: employee, employment, or job-position), and which API surface exposes it (category: system or extension).
System properties (category: system, e.g. employee.givenName, jobPosition.manager) are read-only through this endpoint. To update them, use the write endpoints of the corresponding primary resource (e.g. PATCH /lucca-api/employees/{id}).Extension properties (category: extension, e.g. e_tShirtSize, e_children) are absent from every primary resource representation and only readable through the employee-attributes and employee-attribute-definitions endpoints. There is no other API endpoint for them.

​
Key Concepts

​
Definitions vs. Values

Employee attributes unify two kinds of properties into a single model:
  • System properties that Lucca defines on primary resources (e.g. employee.givenName, jobPosition.manager).
  • Extension properties attached to a primary resource beyond its system properties (e.g. e_tShirtSize), whether created by your organization or added by a Lucca application.
Both are accessed through the same pair of concepts:

employee-attribute-definition

Describes a property: its id, human-readable name, the JSON schema of its value, the targetType (employee, employment, or job-position) indicating which primary resource it belongs to, the category (system or extension) indicating which API surface exposes it, and isValueReadOnly indicating whether its values can be modified through the API.

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 the value is valid.

​
System vs. Extension Attributes

The category of a definition tells you which API surface exposes its values. It says nothing about who provides the property: a property added by a Lucca application carries extension, just like one your organization created. The extensions node of a primary resource, when present, carries the values of the extension definitions targeting that resource.
Extension property IDs always start with e_ (e.g. e_tShirtSize), making them easy to distinguish from system ones (e.g. employee.givenName).

​
What isValueReadOnly Promises

isValueReadOnly tells you whether the values of a definition can be modified through the Lucca API. It is derived from the actual write capability of the property, so it may change as the API evolves: the fact that every extension definition currently carries false reflects the present state, not a rule. Read it with these limits in mind:
  • false only promises that an existing value may be modified. Creating a value or deleting an occurrence have their own conditions, which the definition does not describe.
  • It describes what the account exposes, not the rights of the caller. A write on a definition with isValueReadOnly: false may still be denied with 403 if your client application lacks the scope or the hr file section access.
  • Some system properties are read-only because their modification goes through another resource. For example, employment.legalEntity cannot be modified: an employee changes legal entity through a new employment.

​
Applicability

Because many attributes come from time-bounded resources like employment or job-position, each employee-attribute exposes an applicability window:
  • 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, e_tShirtSize), 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.

​
Access

​
OAuth Scopes

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.

​
HR File Sections and Business Establishments

Beyond OAuth scopes, two additional constraints apply when reading employee attributes:
  • Business establishments: you may only access attributes of employees whose applicable business establishment (see employee.applicableJobPosition.businessEstablishment) is accessible to your client application.
  • HR file sections: each attribute definition is associated with an employee hr file section. Sections are not exposed by the v5 Lucca API but are visible in the user interface. Your integration may only access attributes belonging to sections explicitly granted to it (see below).

​
Granting access to hr file sections

When configuring your OAuth client, the employee-attributes.readonly (or .readwrite) scope requires you to select the specific hr file sections your integration can read. Only attributes attached to one of the selected sections will be returned by the API.
If you select all sections, the API will return no employee-attribute at all (i.e. responses will be empty).
Security best practice: as a Lucca admin, create a dedicated hr file section for your integration and attach to it only the attributes it needs — no more.This approach:
  • Makes your integration’s data footprint explicit and auditable.
  • Prevents accidental exposure of sensitive attributes attached to other sections.
  • Reduces the blast radius of a compromised access token: the attacker can only access attributes in the granted sections, not the entire account.

​
Common Workflows

​
1. Discover Available Definitions

Before reading values, you may want to discover which attribute definitions exist on the account.
You can narrow results with these query parameters: A definition response looks like this:
The targetType tells you which underlying resource the value comes from: The category tells you where else, if anywhere, the value can be read: a system property is also readable on the resource named by targetType, an extension property is not.

​
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:
A response item looks like this:

​
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:
For object-typed attributes (i.e. definitions whose schema.type is "object"), use dot-notation to target a specific sub-property of the value:
Filtering on value performs a strict equality check. Partial matches and range filters are not supported.

​
3. Read a Single Attribute

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

​
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: 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.

​
Listing Available Values for Taxonomy Properties

When a definition uses the taxonomy-label-reference schema, the employee can only pick from a predefined list of values. To retrieve that list, use the taxonomy.id from the definition and call:
For example, the “T-shirt size” definition above has "taxonomy": {"id": "45"}. Calling GET /lucca-api/taxonomy-labels?taxonomy.id=45 returns the available labels (Small, Medium, Large, etc.).
This requires the taxonomies.readonly scope. See Get Started With Taxonomies for a full walkthrough.

​
Example: Multi-valued Object Attribute (Children)

This example walks through an extension 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

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:
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.

Pagination

Learn how cursor-based pagination works.

Filtering

Learn more about filtering collections.