List employees

Security: OAuth 2.0

Scopes:

- employees.readonly
- employees.readwrite

Business-establishments: Employee's applicable job-position business-establishment.

About authentication

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

If-None-Match

string

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

If-Match

string

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

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

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

string[]

Filter out employees on their ID.

Maximum array length: 100

Minimum string length: 1

(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

applicableEmployment.legalEntity.id

string[]

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

Maximum array length: 100

Minimum string length: 1

applicableEmployment.remoteId

string[]

Filter out employees on their active employment remoteId.

Maximum array length: 100

Minimum string length: 1

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.

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.

applicableEmployment.template.id

string[]

Filter out employees on their applicable employment template IDs.

Maximum array length: 100

Minimum string length: 1

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

applicableJobPosition.remoteId

string[]

Filter out employees on their applicable job-position remoteId.

Maximum array length: 100

Minimum string length: 1

applicableJobPosition.businessEstablishment.id

string[]

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

Maximum array length: 100

Minimum string length: 1

applicableJobPosition.department.id

string[]

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

Maximum array length: 100

Minimum string length: 1

applicableJobPosition.manager.id

string[]

Filter out employees on their manager's IDs.

Maximum array length: 100

Minimum string length: 1

applicableJobPosition.jobQualification.id

string[]

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

Maximum array length: 100

Minimum string length: 1

applicableJobPosition.jobQualification.remoteId

string[]

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

Maximum array length: 100

Minimum string length: 1

applicableJobPosition.occupationCategory.id

string[]

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

Maximum array length: 100

Minimum string length: 1

applicableJobPosition.occupationCategory.remoteId

string[]

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

Maximum array length: 100

Minimum string length: 1

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.

Response

A collection of employee resources.

type

string

required

Allowed value: "employees"

url

string<uri>

required

items

employee · object[]

required

Paginated list of employee resources.

Maximum array length: 100

Show child attributes

items.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 - 255

items.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 - 255

items.email

null | string<email>

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

items.id

string

Minimum string length: 1

items.type

string

Allowed value: "employee"

items.url

string<uri>

items.remoteId

null | string

Must be unique.

Required string length: 1 - 100

items.portrait

portrait-reference · object

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

Show child attributes

items.portrait.id

string

required

Minimum string length: 1

items.portrait.type

string

Allowed value: "portrait"

items.portrait.url

string<uri>

items.employeeNumber

null | string

Required string length: 1 - 50

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

items.birthDay

object

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

Show child attributes

items.birthDay.day

integer<int32>

required

Starts at "1". Maximum depends on the month.

Required range: 1 <= x <= 31

items.birthDay.month

integer<int32>

required

Starts at "1" and goes up to "12" (included).

Required range: 1 <= x <= 12

items.phoneNumber

string<phone> | null

Professional phone number of this employee.

Example:

"+3356565656"

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

Show child attributes

items.applicableEmployment.id

string

Minimum string length: 1

items.applicableEmployment.type

string

Allowed value: "employment"

items.applicableEmployment.url

string<uri>

items.applicableJobPosition

object

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

Show child attributes

items.applicableJobPosition.id

string

Minimum string length: 1

items.applicableJobPosition.type

string

Allowed value: "job-position"

items.applicableJobPosition.url

string<uri>

items.createdAt

string<date-time-offset>

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

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

items.links

object

Show child attributes

items.links.employments

Link · object

Object that represents an hyperlink.

Show child attributes

items.links.employments.href

string<uri>

required

URL to the related object.

items.links.jobPositions

Link · object

Object that represents an hyperlink.

Show child attributes

items.links.jobPositions.href

string<uri>

required

URL to the related object.

items.links.personalRecord

Link · object

Object that represents an hyperlink.

Show child attributes

items.links.personalRecord.href

string<uri>

required

URL to the related object.

totalCount

integer<int64> | null

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

Required range: x >= 0

embedded

object

Show child attributes

embedded.employment

object

Dictionary of employments indexed by ID.

Show child attributes

embedded.employment.{key}

employment · object

The employment resource represents a relationship between an employee and a legal-entity over a continuous period. It may actually represent a work contract, an internship agreement, a contractor's contract, etc...

The actual job of the employee is defined through the job-position resource, which references an employment. Over the course of his/her employment, the employee may occupy several job-positions.

Show child attributes

embedded.employment.{key}.legalEntity

Reference to a legal-entity · object

required

Read-only. Reference to a legal-entity. Inferred from the business-establishment of its first job-position.

Show child attributes

embedded.employment.{key}.legalEntity.id

string

required

Minimum string length: 1

embedded.employment.{key}.legalEntity.type

enum<string>

Available options:

legal-entity

Allowed value: "legal-entity"

embedded.employment.{key}.legalEntity.url

string<uri>

embedded.employment.{key}.start

object

required

Show child attributes

embedded.employment.{key}.start.date

string<date>

required

Date of the first day (included) of this employment.

embedded.employment.{key}.template

employment-template-reference · object

required

Reference to an employment-template resource.

Show child attributes

embedded.employment.{key}.template.id

string

required

Minimum string length: 1

embedded.employment.{key}.template.type

enum<string>

Available options:

employment-template

Allowed value: "employment-template"

embedded.employment.{key}.template.url

string<uri>

embedded.employment.{key}.id

string

Minimum string length: 1

embedded.employment.{key}.type

string

Allowed value: "employment"

embedded.employment.{key}.url

string<uri>

embedded.employment.{key}.remoteId

null | string

Resource identifier in a third-party system.

Required string length: 1 - 200

embedded.employment.{key}.employee

employee-reference · object

Reference to an employee resource.

Show child attributes

embedded.employment.{key}.employee.id

string

required

Minimum string length: 1

embedded.employment.{key}.employee.type

enum<string>

Available options:

employee

Allowed value: "employee"

embedded.employment.{key}.employee.url

string<uri>

embedded.employment.{key}.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

embedded.employment.{key}.end

object

Show child attributes

embedded.employment.{key}.end.date

string<date>

required

Date of the last day (included) of this employment. After this date, this employment is considered terminated.

Leave null for permanent employments (as long as the employee is kept), and set the date of the last day in case of a fixed-term employment.

EndsOn date must be greater or equal than StartsOn date.

embedded.employment.{key}.document

file-reference · object

Reference to a file resource.

Show child attributes

embedded.employment.{key}.document.id

string

required

Minimum string length: 1

embedded.employment.{key}.document.type

enum<string>

Available options:

file

Allowed value: "file"

embedded.employment.{key}.document.url

string<uri>

Example:

{
  "id": "9283sdf",
  "type": "file",
  "url": "https://example.ilucca.net/lucca-api/files/9283sdf"
}

embedded.employment.{key}.createdAt

string<date-time-offset>

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

embedded.employment.{key}.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.

embedded.employment.{key}.links

object

Show child attributes

embedded.employment.{key}.links.jobPositions

Link · object

Link to the related job-positions for this employment.

Show child attributes

embedded.employment.{key}.links.jobPositions.href

string<uri>

required

URL to the related object.

embedded.employment.{key}.links.probationaryPeriods

Link · object

Link to the related probationary-periods for this employment.

Show child attributes

embedded.employment.{key}.links.probationaryPeriods.href

string<uri>

required

URL to the related object.

Example:

{
  "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"
    }
  }
}

embedded.job-position

object

Dictionary of job-positions indexed by ID.

Show child attributes

embedded.job-position.{key}

job-position · object

The job position represents a stage in an employee's career during one of their employment in a given business-establishment.

It therefore outlines the attributes of the person as a professional (qualifications) and their role in the company as well as who's their manager.

Show child attributes

embedded.job-position.{key}.startsOn

string<date>

required

Effective date of this job-position for this employee.

Cannot be outside the range of the employment.

This should be considered "applicable" based on the related employment business-establishment timezone.

embedded.job-position.{key}.businessEstablishment

business-establishment-reference · object

required

Reference to a business-establishment resource.

Show child attributes

embedded.job-position.{key}.businessEstablishment.id

string

required

Minimum string length: 1

embedded.job-position.{key}.businessEstablishment.type

enum<string>

Available options:

business-establishment

Allowed value: "business-establishment"

embedded.job-position.{key}.businessEstablishment.url

string<uri>

embedded.job-position.{key}.department

department-reference · object

required

Reference to a department resource.

Show child attributes

embedded.job-position.{key}.department.id

string

required

Minimum string length: 1

embedded.job-position.{key}.department.type

enum<string>

Available options:

department

Allowed value: "department"

embedded.job-position.{key}.department.url

string<uri>

embedded.job-position.{key}.id

string

Minimum string length: 1

embedded.job-position.{key}.type

string

Allowed value: "job-position"

embedded.job-position.{key}.url

string<uri>

embedded.job-position.{key}.remoteId

null | string

Resource identifier in a third-party system. No unicity constraint: two job-positions may have the same value.

Required string length: 1 - 1024

embedded.job-position.{key}.employment

employment-reference · object

Reference to an employment resource.

Show child attributes

embedded.job-position.{key}.employment.id

string

required

Minimum string length: 1

embedded.job-position.{key}.employment.type

enum<string>

Available options:

employment

Allowed value: "employment"

embedded.job-position.{key}.employment.url

string<uri>

embedded.job-position.{key}.employee

employee-reference · object

Read-only. Reference to the employment's employee.

Show child attributes

embedded.job-position.{key}.employee.id

string

Minimum string length: 1

embedded.job-position.{key}.employee.type

enum<string>

Available options:

employee

Allowed value: "employee"

embedded.job-position.{key}.employee.url

string<uri>

embedded.job-position.{key}.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

embedded.job-position.{key}.endsOn

null | string<date>

Read-only. End date (included) of this job-position effectiveness.

Is calculated from the startsOn property of the closest next job-position, or the endsOn date of the parent employment.

This should be considered "applicable" based on the related employment business-establishment timezone.

Must be greater or equal than StartsOn date.

embedded.job-position.{key}.jobTitle

null | string

Short description of the job occupied by this employee.

Required string length: 1 - 1024

embedded.job-position.{key}.jobQualification

job-qualification-reference · object

Reference to a job-qualification resource.

Show child attributes

embedded.job-position.{key}.jobQualification.id

string

required

Minimum string length: 1

embedded.job-position.{key}.jobQualification.type

enum<string>

Available options:

job-qualification

Allowed value: "job-qualification"

embedded.job-position.{key}.jobQualification.url

string<uri>

embedded.job-position.{key}.manager

employee-reference · object

Reference to another employee, who is considered to be this employee's manager.

Show child attributes

embedded.job-position.{key}.manager.id

string

required

Minimum string length: 1

embedded.job-position.{key}.manager.type

enum<string>

Available options:

employee

Allowed value: "employee"

embedded.job-position.{key}.manager.url

string<uri>

embedded.job-position.{key}.occupationCategory

occupation-category-reference · object

Reference to an occupation-category resource.

Show child attributes

embedded.job-position.{key}.occupationCategory.id

string

required

Minimum string length: 1

embedded.job-position.{key}.occupationCategory.type

enum<string>

Available options:

occupation-category

Allowed value: "occupation-category"

embedded.job-position.{key}.occupationCategory.url

string<uri>

embedded.job-position.{key}.workingTimeArrangement

working-time-arrangement-reference · object

Reference to a working-time-arrangement resource.

Show child attributes

embedded.job-position.{key}.workingTimeArrangement.id

string

required

Minimum string length: 1

embedded.job-position.{key}.workingTimeArrangement.type

enum<string>

Available options:

working-time-arrangement

Allowed value: "working-time-arrangement"

embedded.job-position.{key}.workingTimeArrangement.url

string<uri>

embedded.job-position.{key}.document

document-reference · object

Reference to a document resource.

Show child attributes

embedded.job-position.{key}.document.id

string

required

Minimum string length: 1

embedded.job-position.{key}.document.type

enum<string>

Available options:

document

Allowed value: "document"

embedded.job-position.{key}.document.url

string<uri>

embedded.job-position.{key}.notes

null | string

Optional notes about this job-position change.

Maximum string length: 500

embedded.job-position.{key}.t9n

object

Show child attributes

embedded.job-position.{key}.t9n.jobTitle

Translations · object

Used for translation purposes. Object is structured as a dictionary whose keys refer to translated properties of the parent object, and whose values are a dictionary of supported languages.

On the parent object, the translated property value is considered the "invariant" translation. It is expected to show this value whenever the user's language has no translation in t9n.

Languages are identified through their RFC 4646 language tag.

Show child attributes

embedded.job-position.{key}.t9n.jobTitle.de-DE

string | null

German (Germany)

embedded.job-position.{key}.t9n.jobTitle.en-US

string | null

English (United States of America)

embedded.job-position.{key}.t9n.jobTitle.en-GB

string | null

English (Great Britain)

embedded.job-position.{key}.t9n.jobTitle.es-ES

string | null

Spanish (Spain)

embedded.job-position.{key}.t9n.jobTitle.fr-FR

string | null

French (France)

embedded.job-position.{key}.t9n.jobTitle.fr-CH

string | null

French (Switzerland)

embedded.job-position.{key}.t9n.jobTitle.it-IT

string | null

Italian (Italy)

embedded.job-position.{key}.t9n.jobTitle.nl-BE

string | null

Dutch (Belgium)

embedded.job-position.{key}.t9n.jobTitle.nl-NL

string | null

Dutch (Netherlands)

embedded.job-position.{key}.t9n.jobTitle.pt-PT

string | null

Portuguese (Portugal)

embedded.job-position.{key}.updatedAttributes

enum<string>[]

List of attributes that changed compared with this employee previous job-position, even if said job-position was on another employment and/or not immediately sequential.

List of attributes that can change for a job-position.

Available options:

remoteId,

jobTitle,

jobQualification,

occupationCategory,

workingTimeArrangement,

department

embedded.job-position.{key}.createdAt

string<date-time-offset>

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

embedded.job-position.{key}.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.

embedded.job-position.{key}.links

object

Example:

{
  "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,
  "t9n": { "jobTitle": { "fr-FR": "Développeur" } },
  "updatedAttributes": ["jobTitle", "jobQualification"],
  "createdAt": "2024-04-15T23:12:54.0001Z",
  "lastUpdatedAt": "2024-04-15T23:12:54.0001Z",
  "links": {}
}

links

Links · object

Links to related resources

Show child attributes

links.prev

Link · object

required

Link to the previous page. Is null on the first page.

Show child attributes

links.prev.href

string<uri>

required

URL to the related object.

links.next

Link · object

required

Link to the next page. Is null on the last page.

Show child attributes

links.next.href

string<uri>

required

URL to the related object.

Overview

Organization

Employee Records

Events & Webhooks

Authorizations

Headers

Query Parameters

Response