Skip to main content
If you are migrating from the legacy directory API (v3 and v4), check out both migration guides:

​
The employee model

The employee is a complex resource that is represented through several objects.
1

Employee

The employee resource represents the public face of the employee, i.e. all of their attributes that would be commonly known to anyone in the company.
2

Employee-Personal-Record

The employee-personal-record is a record that extends an employee and contains personal information about the employee: personal contact information, emergency contact, social security number, etc…
3

Employment

The employment represents the relationship between an employee and a legal-entity. It can be a work-contract, a training agreement, the contract of a contractor, etc… An employment has a start date and optional end date. No two employments may overlap for a given employee.
Employments also dictate access rights, as only employees having an “active” employment may access their Lucca account.
4

Job-Position

The job-position represents a temporary position occupied by an employee during one of their employment. It indicates the employee’s business-establishment, manager, job-qualification, department, job title, occupation-category, etc… The list of job-positions occupied by an employee represents their whole career in the company.
In the Lucca API model, an employee may have more than one employment, and occupy several job-positions over this single employment (without overlaps, though). This makes it possible to keep track of the whole employee’s career. But in some cases, clients may just need to figure out the employee’s single current employment and job-position. For example to retrieve their current department and manager.In order to facilitate this, the employee resource has two extra attributes:
  • applicableJobPosition: which references the current job-position, i.e. the one whose start and end dates contain “now”;
  • applicableEmployment: which references the current employment, i.e. the one who has the applicable job-position.
If you have access to these referenced resources, then they can also be embedded in the employee response, in which case you do not even have to follow their URLs.As a result, an employee’s manager can be retrieved thusly:
const options = {
    method: 'GET',
    headers: {'Api-Version': '<api-version>', Authorization: 'Bearer <access_token>'}
};

let req = fetch('https://{account}-{sandboxName}.sandbox.{server}.luccasoftware.com/lucca-api/employees/{id}', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));

const json = JSON.parse(response);
const managerRef = json.embedded["job-position"][json.applicableJobPosition.id]?.manager;
const manager = json.embedded["employee"][managerRef.id];

​
Reading Employee Data Uniformly

The employee data model is spread across several resources (employee, employment, job-position, and their extensions). When you need to query properties across these resources in a consistent way — for example, to build a directory view or sync employee data to an external system — the employee-attributes API offers a single endpoint that surfaces any property of any employee, regardless of which underlying resource it lives in.

Get Started With Employee Attributes

Learn how to read any employee property — built-in or custom — from a single, uniform endpoint.