> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started With Employees

> Learn more about the employee resource and its relations with other resources.

<Tip>
  If you are migrating from the legacy directory API (v3 and v4), check out both migration guides:

  * [Migrating from V3 Users](/api-reference/legacy/directory/guides/users-migration);
  * [Migrating from V4 Work Contracts](/api-reference/legacy/directory/guides/work-contracts-migration).
</Tip>

## The employee model

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

<Steps titleSize="h3">
  <Step title="Employee">
    The [employee](./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.
  </Step>

  <Step title="Employee-Personal-Record">
    The [employee-personal-record](./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...
  </Step>

  <Step title="Employment">
    The [employment](../employments/employment) represents the relationship
    between an employee and a [legal-entity](../organization/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.

    <Note>
      Employments also dictate access rights, as only employees
      having an "active" employment may access their Lucca account.
    </Note>
  </Step>

  <Step title="Job-Position">
    The [job-position](../employments/job-position) represents a temporary
    position occupied by an employee during one of their employment. It indicates the employee's
    [business-establishment](../organization/business-establishment),
    manager,
    [job-qualification](../employee-job-qualifications/get-started),
    [department](../organization/department),
    job title,
    [occupation-category](../employee-occupation-categories/get-started),
    etc...
    The list of job-positions occupied by an employee represents their whole career
    in the company.
  </Step>

  <Step title="Employee-Attribute">
    In addition to the four resources above, every attribute of the employee, whether built into the Lucca system
    (e.g. `givenName`, `legalGender`, `birthDate`, etc.) or custom to your organization to fit your needs (e.g. `e_teeShirtSize`, `e_favoriteColor`, etc.),
    is also exposed through the [employee-attribute](../employee-attributes/employee-attribute) resource. It provides a single, uniform endpoint
    to read any employee attribute, regardless of the underlying resource it belongs to.

    <Note>
      Custom (i.e. not system built-in) employee-attributes are exclusively managed through `employee-attributes` and their [definitions](../employee-attributes/employee-attribute-definition).
      There is no dedicated resource and/or API endpoint for them in the Lucca API.
    </Note>
  </Step>
</Steps>

<Accordion title="How can I retrieve the current state of an employee's employment and/or job-position?">
  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:

  ```javascript theme={null}
  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];
  ```
</Accordion>

***

## Reading Employee Attributes Uniformly

To read any employee attribute across all resources use the `employee-attributes` endpoint.

<Card title="Get Started With Employee Attributes" href="../employee-attributes/get-started" icon="tag">
  Learn how to read any employee attribute, built-in or custom, through a single and uniform endpoint.
</Card>