List employees
Returns a paginated list of employees.
Access
Access
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
The Lucca API implements the oAuth 2 protocol with the client-credentials-flow. Refer to RFC8725.
Headers
Set the API version.
2024-11-01 "2024-11-01"10"2024-11-01"
Query Parameters
Cursor of the page to retrieve: links.next.cursor or links.prev.cursor of a previous response, which is also the page value of their href.
Cursors are opaque: don't build or modify them. An invalid cursor gets a 400 Bad Request.
Read more about pagination.
Number of items per page. Defaults to 25. Maximum is 1,000. Read more about pagination.
0 <= x <= 1000Filter out employees on their status.
100Read-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.
active, upcoming, deactivated 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.
^(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])|\.\.)--(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])|\.\.)$"2024-01-01--2024-12-31"
"..--2024-12-31"
"2024-01-01--.."
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.
^(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])|\.\.)--(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])|\.\.)$"2024-01-01--2024-12-31"
"..--2024-12-31"
"2024-01-01--.."
Order employees by given instruction. Read more about sorting. Default: id.
100id, -id, familyName, -familyName, createdAt, -createdAt Filter out employees on their lastUpdatedAt timestamp (range).
ISO 8601 formatted date-time-offset-range string.
Designed as a right-half-open interval: end is excluded [start, end).
Each bound must be written as yyyy-MM-ddTHH:mm:ss, with optional fractional seconds, followed by an offset (Z or ±hh:mm).
Seconds are required. A timestamp read from a response payload can be reused as a bound as is,
within a precision of 100 ns.
Examples:
2026-01-01T00:00:00Z--2027-01-01T00:00:00Z: from Jan. 1st 2026 until Dec. 31st 2026...--2026-06-01T00:00:00Z: until May 31st 2026 (included).2026-05-26T00:00:00Z--..: from May 26th 2026.2026-05-26T07:23:29.7977299+00:00--..: from May 26th 2026, 07:23:29.7977299 UTC.
^(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)|\.\.)--(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)|\.\.)$"2026-01-01T00:00:00Z--2027-01-01T00:00:00Z"
"..--2026-06-01T00:00:00Z"
"2026-05-26T00:00:00Z--.."
"2026-05-26T07:23:29.7977299+00:00--.."
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 benullwhen you do not have access to the resource (or action). Includes the download links of the files the resource references, underlinks.files.totalCount: only applicable on collections (i.e. lists of resources), gives the total number of items across all pages.
Read more about expanding responses.
embedded, links, totalCount Response
OK
A collection of employee resources.