Get Started With Employee Attributes

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 built-in properties defined by Lucca (e.g. employee.givenName, personal.legalGender, jobPosition.manager). In addition, your organization can define its own custom properties (e.g. a “T-shirt size” field) and attach them to any of these primary resources. In practice, this means a single piece of information about an employee may live on any of these resources, as either a system or custom property. Employee attributes provide a single, uniform endpoint to access any property — system built-in or custom — 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, and which primary resource it targets (employee, employment, or job-position).

System built-in properties (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}).Custom properties (e.g. e_tShirtSize, e_children) are exclusively managed — only read as of now — 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 built-in properties that Lucca defines on primary resources (e.g. employee.givenName, jobPosition.manager).
Custom properties that your organization creates and attaches to a primary resource (e.g. e_tShirtSize).

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, and the targetType (employee, employment, or job-position) indicating which primary resource it belongs to. Definitions are either provided by Lucca (for system properties) or created by your organization (for custom 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 the value is valid.

System vs. Custom Attributes

Although both appear as employee-attribute values, system and custom attributes differ in how they are managed:

	System	Custom
Origin	Defined by Lucca. Present on every account.	Created by your organization to fit your needs.
Examples	`employee.givenName`, `employee.birthDate`, `jobPosition.manager`, `jobPosition.department`	`e_tShirtSize`, `e_favoriteColor`, `e_children`
Read via	Primary resource endpoints or `employee-attributes`	`employee-attributes`
Write via	Primary resource endpoints (e.g. `PATCH /lucca-api/employees/{id}`)	Not implemented yet
Definition managed by	Lucca — always present, cannot be modified.	Your organization, via `employee-attribute-definitions`.

Custom property IDs always start with e_ (e.g. e_tShirtSize), making them easy to distinguish from system ones (e.g. employee.givenName).

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, 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

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.

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.
Avoids the “all sections selected = empty response” pitfall.
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.

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
`employee`	A system or custom property attached to the `employee` resource
`employment`	A system or custom property attached to the `employment` resource
`job-position`	A system or custom property attached to the `job-position` resource

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"
}

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

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

System vs. Custom Attributes

Applicability

Multiple Values

Access

OAuth Scopes

HR File Sections and Business Establishments

Granting access to hr file sections

Common Workflows

1. Discover Available Definitions

2. Read Attributes for a Specific Employee

Filtering on `value`

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

Documentation Index

​What Are Employee Attributes?

​Key Concepts

​Definitions vs. Values

employee-attribute-definition

employee-attribute

​System vs. Custom Attributes

​Applicability

​Multiple Values

​Access

​OAuth Scopes

​HR File Sections and Business Establishments

​Granting access to hr file sections

​Common Workflows

​1. Discover Available Definitions

​2. Read Attributes for a Specific Employee

​Filtering on value

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

System vs. Custom Attributes

Applicability

Multiple Values

Access

OAuth Scopes

HR File Sections and Business Establishments

Granting access to hr file sections

Common Workflows

1. Discover Available Definitions

2. Read Attributes for a Specific Employee

Filtering on `value`

3. Read a Single Attribute

Understanding the `value` Property

Example: Multi-valued Object Attribute (Children)

The Definition

The Corresponding Attributes

Paginating Results