GET
/
lucca-api
/
employees
/
{id}
Retrieve an employee
curl --request GET \
  --url https://{host}/lucca-api/employees/{id} \
  --header 'Api-Version: <api-version>' \
  --header 'Authorization: Bearer <token>'
{
  "id": "416",
  "type": "employee",
  "url": "https://example.ilucca.net/lucca-api/employees/416",
  "remoteId": "00002345",
  "portrait": {
    "id": "66512232",
    "type": "portrait",
    "url": "https://example.ilucca.net/lucca-api/portraits/66512232"
  },
  "givenName": "Edward",
  "familyName": "Atkinson",
  "employeeNumber": "E000124",
  "status": "active",
  "email": "eatkinson@acme.corp",
  "birthDay": {
    "day": 22,
    "month": 12
  },
  "phoneNumber": "+33145784512",
  "applicableEmployment": {
    "id": "154",
    "type": "employment",
    "url": "https://example.ilucca.net/lucca-api/employments/154"
  },
  "applicableJobPosition": {
    "id": "74",
    "type": "job-position",
    "url": "https://example.ilucca.net/lucca-api/job-positions/74"
  },
  "createdAt": "2024-04-15T23:12:54.0001Z",
  "lastUpdatedAt": "2024-04-15T23:12:54.0001Z",
  "links": {
    "employments": {
      "href": "https://example.ilucca.net/lucca-api/employments?employee.id=416"
    },
    "jobPositions": {
      "href": "https://example.ilucca.net/lucca-api/job-positions?employment.employee.id=416"
    },
    "personalRecord": {
      "href": "https://example.ilucca.net/lucca-api/employee-personal-records?employee.id=416"
    }
  },
  "embedded": {
    "employment": {
      "4561": {
        "id": "4561",
        "type": "employment",
        "url": "https://example.ilucca.net/lucca-api/employments/4561",
        "remoteId": "EMPLOYMENT#4512-ac",
        "employee": {
          "id": "416",
          "type": "employee",
          "url": "https://example.ilucca.net/lucca-api/employees/416"
        },
        "legalEntity": {
          "id": "123",
          "type": "legal-entity",
          "url": "https://example.ilucca.net/lucca-api/legal-entities/123"
        },
        "start": {
          "date": "2024-01-01"
        },
        "end": null,
        "document": {
          "id": "74411",
          "type": "file",
          "url": "https://example.ilucca.net/lucca-api/files/74411"
        },
        "template": {
          "id": "4",
          "type": "employment-template",
          "url": "https://example.ilucca.net/lucca-api/employment-templates/4"
        },
        "createdAt": "2024-04-15T23:12:54.0001Z",
        "lastUpdatedAt": "2024-04-15T23:12:54.0001Z",
        "links": {
          "jobPositions": {
            "href": "https://example.ilucca.net/lucca-api/job-positions?employment.id=4561"
          },
          "trialPeriods": {
            "href": "https://example.ilucca.net/lucca-api/trial-periods?employment.id=4561"
          }
        }
      }
    },
    "job-position": {
      "74": {
        "id": "74",
        "type": "job-position",
        "url": "https://example.ilucca.net/lucca-api/job-positions/74",
        "remoteId": null,
        "employment": {
          "id": "28",
          "type": "employment",
          "url": "https://example.ilucca.net/lucca-api/employments/28"
        },
        "employee": {
          "id": "416",
          "type": "employee",
          "url": "https://example.ilucca.net/lucca-api/employees/416"
        },
        "startsOn": "2024-01-01",
        "endsOn": null,
        "businessEstablishment": {
          "id": "5",
          "type": "business-establishment",
          "url": "https://example.ilucca.net/lucca-api/business-establishments/5"
        },
        "jobTitle": "Developer",
        "jobQualification": {
          "id": "982",
          "type": "job-qualification",
          "url": "https://example.ilucca.net/lucca-api/job-qualifications/982"
        },
        "manager": {
          "id": "541",
          "type": "employee",
          "url": "https://example.ilucca.net/lucca-api/employees/541"
        },
        "occupationCategory": {
          "id": "12",
          "type": "occupation-category",
          "url": "https://example.ilucca.net/lucca-api/occupation-categories/12"
        },
        "workingTimeArrangement": {
          "id": "23",
          "type": "working-time-arrangement",
          "url": "about:blank"
        },
        "department": {
          "id": "32",
          "type": "department",
          "url": "https://example.ilucca.net/lucca-api/departments/32"
        },
        "document": null,
        "notes": null,
        "updatedAttributes": [
          "jobTitle",
          "jobQualification"
        ],
        "createdAt": "2024-04-15T23:12:54.0001Z",
        "lastUpdatedAt": "2024-04-15T23:12:54.0001Z",
        "links": null
      }
    }
  }
}

Authorizations

​
Authorization
string
header
required

The Lucca API implements the oAuth 2 protocol with the client-credentials-flow. Refer to RFC8725.

Headers

​
Api-Version
enum<string>
required

Set the API version.

Available options:
TitleConst
2024-11-01
Examples:

"2024-11-01"

​
If-None-Match
string

Only execute the request if current cached version of the resource does not match the one given here.

Examples:

"W/q5sd4w2x1c1gfdg"

​
If-Match
string

Only execute the request if current cached version of the resource matches the one given here. Useful to avoid concurrency conflicts.

Examples:

"W/q5sd4w2x1c1gfdg"

​
Accept-Encoding
string

List of compression algorithms you support.

Path Parameters

​
id
string
required

Identifier of the employee to retrieve.

Minimum length: 1

Query Parameters

​
include
enum<string>[]

Include metadata:

  • embedded: the partial or complete representations of related resources (e.g. the employee the resource belongs to).
  • links: links to related resources or actions (e.g. approving a leave-request). May be null when you do not have access to the resource (or action).
  • totalCount: only applicable on collections (i.e. lists of resources), gives the total number of items across all pages.

Read more about expanding responses.

Response

OK

The employee represents the public face of an employee in the system. Note that an employee can also represent a trainee, an intern, a contractor, etc...

The applicableEmployment property references the employee's employment that is:

  • currently in effect if the employee is "active".
  • will first be in effect if the employee has an employment starting in the future (either the first or a new one).
  • was last in effect if the employee is no longer employed and is not expected to be re-remployed in the future.

The applicableJobPosition property references the employee's job-position that matches the same logic. Embedded resources on a employee(s) response. An employee resource.

​
id
string
required
Minimum length: 1
​
type
string
required
Allowed value: "employee"
​
url
string<uri>
required
​
givenName
string
required

Name given at birth. In the U.S.A., the first name of a person. In French: "prénom". Leading and trailing spaces are automatically removed.

Required string length: 1 - 100
​
familyName
string
required

Name inherited from the person's family. In the U.S.A., the last name of a person. In French: "nom (de famille)". Leading and trailing spaces are automatically removed.

Required string length: 1 - 100
​
email
string<email> | null
required

Professional email of this employee. "<" and ">" characters are forbidden. Some domains are blacklisted and may thus result in 400 errors.

Required string length: 3 - 255
​
remoteId
string | null

Must be unique.

Required string length: 1 - 100
​
portrait
object | null

Reference to the employee's portrait, which is a file (picture) representing them. Reference to a portrait resource.

Examples:
{
  "id": "9283sdf",
  "type": "portrait",
  "url": "https://example.ilucca.net/lucca-api/portraits/9283sdf"
}
​
employeeNumber
string | null
Minimum length: 1
​
status
enum<string>

Read-only. The employee status is calculated from the employee's employments.

  • active: employee has an employment as of today.
  • upcoming: employee currently has no employment but will have one in the future.
  • deactivated: employee used to have an employment but no longer does.
Available options:
active,
upcoming,
deactivated
Examples:

"active"

​
birthDay
object | null

Year-less date of birth.

Read-only, as it is infered from the employee-personal-record birthDate. Take note that month starts at "1" and not zero, i.e. "1" is for January, "2" for February, etc...

​
phoneNumber
string<phone> | null

Professional phone number of this employee. Phone number.

Examples:

"+3356565656"

​
applicableEmployment
object

Read-only. Reference to the applicable employment of this employee. If the employee status is "deactivated", then references their last employment. If the employee status is "upcoming", then references their closest next employment.

​
applicableJobPosition
object

Read-only. Reference to the active job-position of this employee. Matches the same logic than the "applicableEmployment".

​
createdAt
string<date-time-offset>

Read-only. UTC timestamp of the moment this object was created.

Examples:

"2023-01-23T12:45:23.1234Z"

​
lastUpdatedAt
string<date-time>

Read-only. UTC timestamp of the moment this object was last updated. Set upon creation, update or deletion of the object.

Examples:

"2023-01-23T12:45:23.1234Z"

​
links
object
​
embedded
object | null