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 exclusively managed 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.

Downloading File Values

A file value only holds the file id: its url does not give access to the file. Read the attribute with ?include=links and follow links.files["{fileId}"].href with the same Authorization header. Files nested in an object value each get their own entry.
Downloading requires the files.readonly scope in addition to employee-attributes.readonly. See Get Started With Files for the 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.

Writing Attribute Values

Currently covers extension properties (category: extension, IDs starting with e_). System properties (category: system) remain read-only through this endpoint — update them via the write endpoints of their primary resource (e.g. PATCH /lucca-api/employees/{id}).All write calls require the employee-attributes.readwrite scope, and the targeted attribute must belong to an hr file section granted to your integration.

Create a Value

POST /lucca-api/employee-attributes creates a new value. The body identifies the definition, the employee, and the value itself. The employee is always required; also send the employment (and the jobPosition) when the definition targetType is employment or job-position. The value must match the schema declared on the definition (see Understanding the value Property). For a simple scalar property:
For a reference property (e.g. a taxonomy-label-reference like e_tShirtSize), send only the id of the referenced resource — type and url are read-only:
For an object (composite) property, send an object whose properties match the definition schema. The property names are the keys of the definition schema.properties (here e_childGivenName, e_childFamilyName and e_childBirthDate):
For multi-valued definitions (multipleValueHandling is non-null, e.g. e_children), each POST creates one item. The value is a single object — never an array. To add several items, repeat the call once per item.
A successful create returns 201 Created with the new attribute (including its generated id) and a Location header.

Update a Value

Use PATCH /lucca-api/employee-attributes/{id} to change the value of an existing attribute. The value is replaced as a whole: for an object value, send all its properties, including the unchanged ones.
For multi-valued attributes, PATCH targets a single item by its own id — each item is an independent attribute.

Finding Reference IDs (Taxonomy Labels)

When a definition uses the taxonomy-label-reference schema, the value must be one of a predefined list of labels. Use the taxonomy.id from the definition to list the allowed labels and pick the id to send:
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.); use the id of the desired label as the attribute value.
This requires the taxonomies.readonly scope. See Get Started With Taxonomies for a full walkthrough.

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.