Skip to main content
GET
/
lucca-api
/
employees
List employees
curl --request GET \
  --url https://{host}/lucca-api/employees \
  --header 'Api-Version: <api-version>' \
  --header 'Authorization: Bearer <token>'
{
  "type": "employees",
  "url": "https://example.ilucca.net/lucca-api/employees?limit=25",
  "totalCount": 647,
  "items": [
    {
      "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": {
        "portrait": {
          "href": "https://example.ilucca.net/lucca-api/files/66512232?token=eyJhbGciOi"
        },
        "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"
        }
      }
    }
  ],
  "links": {
    "prev": null,
    "next": {
      "href": "https://example.ilucca.net/lucca-api/employees?page=!sdk87Sdh&limit=25"
    }
  },
  "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"
        },
        "status": "active",
        "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"
          },
          "probationaryPeriods": {
            "href": "https://example.ilucca.net/lucca-api/probationary-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"
        },
        "status": "active",
        "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": {}
      }
    }
  }
}
This API endpoint is in beta and may be subject to changes, including breaking changes, without prior notice.
OAuth 2.0 scopes
 employees.readonly
or
 employees.readwrite
EstablishmentsThis API endpoint will filter out results based on accessible business-establishments.You may only access employees whose applicable business-establishments are accessible to you.

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:
2024-11-01
Allowed value: "2024-11-01"
Maximum string length: 10
Example:

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

Example:

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

Example:

"W/q5sd4w2x1c1gfdg"

​
Accept-Encoding
string

List of compression algorithms you support.

Query Parameters

​
page
string

Cursor of the page to retrieve. Read more about pagination.

​
limit
integer
default:25

Number of items per page. Defaults to 25. Maximum is 100. Read more about pagination.

Required range: 0 <= x <= 100
​
search
string

Find an employee by their name. The employee given or family names must start with the given words. Each word can be delimited with any of these delimiters: [' ', '-', '_', ',', '.'].

Minimum string length: 1
​
id
string[]

Filter out employees on their ID.

Maximum array length: 100
Minimum string length: 1
Example:
["123", "456"]
​
email
(string<email> | string)[]

Filter out employees on their email address (strict equality). Comma-separated list. Send "?email=null" to retrieve employees with no email address.

Maximum array length: 100
Required string length: 3 - 255
​
status
enum<string>[]

Filter out employees on their status.

Maximum array length: 100

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
Example:
["active"]
​
applicableEmployment.legalEntity.id
string[]

Filter out employees on their active employment legal-entity IDs.

Maximum array length: 100
Minimum string length: 1
Example:
["12", "13"]
​
applicableEmployment.remoteId
string[]

Filter out employees on their active employment remoteId.

Maximum array length: 100
Minimum string length: 1
Example:
["E001", "E023"]
​
applicableEmployment.startsOn
string<date>

Filter out employees on their active employment startsOn date (strict equality).

​
applicableEmployment.startsOn.between
string<date-range>

Filter out employees on their active employment startsOn date. ISO 8601 formatted date-range string. ISO 8601 formatted date-range string. Examples:

  • 2024-01-01--2024-12-31: from Jan. 1st 2024 until Dec. 31st 2024 (included).
  • ..--2024-12-31: until Dec. 31st 2024.
  • 2024-01-01--..: from Jan. 1st 2024.
Examples:

"2024-01-01--2024-12-31"

"..--2024-12-31"

"2024-01-01--.."

​
applicableEmployment.endsOn

Filter out employees on their applicable employment endsOn date (strict equality).

​
applicableEmployment.endsOn.between
string<date-range>

Filter out employees on their applicable employment endsOn date. ISO 8601 formatted date-range string. ISO 8601 formatted date-range string. Examples:

  • 2024-01-01--2024-12-31: from Jan. 1st 2024 until Dec. 31st 2024 (included).
  • ..--2024-12-31: until Dec. 31st 2024.
  • 2024-01-01--..: from Jan. 1st 2024.
Examples:

"2024-01-01--2024-12-31"

"..--2024-12-31"

"2024-01-01--.."

​
applicableEmployment.template.id
string[]

Filter out employees on their applicable employment template IDs.

Maximum array length: 100
Minimum string length: 1
Example:
["1", "2", "5"]
​
applicableEmployment.template.term
enum<string>[]

Filter out employees on their applicable employment template term.

Maximum array length: 100

Term of an employment.

Available options:
permanent,
fixed
Example:
["permanent"]
​
applicableJobPosition.remoteId
string[]

Filter out employees on their applicable job-position remoteId.

Maximum array length: 100
Minimum string length: 1
Example:
["null", "JP001", "JP002"]
​
applicableJobPosition.businessEstablishment.id
string[]

Filter out employees on their active job-position business-establishment IDs.

Maximum array length: 100
Minimum string length: 1
Example:
["12", "13"]
​
applicableJobPosition.department.id
string[]

Filter out employees on their applicable job-position department IDs.

Maximum array length: 100
Minimum string length: 1
Example:
["123", "452"]
​
applicableJobPosition.manager.id
string[]

Filter out employees on their manager's IDs.

Maximum array length: 100
Minimum string length: 1
Example:
["416", "521"]
​
applicableJobPosition.jobQualification.id
string[]

Filter out employees on their applicable job-position job-qualification IDs.

Maximum array length: 100
Minimum string length: 1
Example:
["25", "28"]
​
applicableJobPosition.jobQualification.remoteId
string[]

Filter out employees on their active job-position job-qualification remoteId.

Maximum array length: 100
Minimum string length: 1
Example:
["null", "JQ001", "JQ002"]
​
applicableJobPosition.occupationCategory.id
string[]

Filter out employees on their active job-position occupation-category IDs.

Maximum array length: 100
Minimum string length: 1
Example:
["5", "12"]
​
applicableJobPosition.occupationCategory.remoteId
string[]

Filter out employees on their active job-position occupation-category remoteId.

Maximum array length: 100
Minimum string length: 1
Example:
["null", "OC001", "OC002"]
​
sort
enum<string>[]

Order employees by given instruction. Read more about sorting. Default: id.

Maximum array length: 100
Available options:
id,
-id,
familyName,
-familyName,
createdAt,
-createdAt
​
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.

Available options:
embedded,
links,
totalCount

Response

OK

A collection of employee resources.

​
type
string
Allowed value: "employees"
​
url
string<uri>
​
totalCount
integer<int64> | null

Total number of employee resources across all pages that satisfy query parameters.

Required range: x >= 0
​
items
employee · object[]

Paginated list of employee resources.

Maximum array length: 100
​
links
Links · object

Links to related resources

​
embedded
object

Embeds the representation of resources related to the employee(s).

Only returned if requested by the API client: ?include=embedded.