List employees

curl --request GET \
  --url https://{host}/lucca-api/employees \
  --header 'Api-Version: <api-version>' \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://{host}/lucca-api/employees"

headers = {
    "Api-Version": "<api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Api-Version': '<api-version>', Authorization: 'Bearer <token>'}
};

fetch('https://{host}/lucca-api/employees', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/lucca-api/employees",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Api-Version: <api-version>",
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/lucca-api/employees"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Api-Version", "<api-version>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{host}/lucca-api/employees")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Api-Version"] = '<api-version>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "instance": "https://example.ilucca.net/lucca-api/leaves/1573",
  "errors": {
    "endsOn": [
      "Invalid period: StartsOn should be before EndsOn."
    ],
    "employeeId": [
      "The employeeId query parameter is required."
    ]
  },
  "extensions": {
    "traceId": "|78777424-49cc27e04281bbfc."
  }
}

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "instance": "https://example.ilucca.net/lucca-api/employees/1573"
}

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Internal Server Error",
  "status": 500,
  "instance": "https://example.ilucca.net/lucca-api/employees/1573"
}

GET

lucca-api

employees

List employees

curl --request GET \
  --url https://{host}/lucca-api/employees \
  --header 'Api-Version: <api-version>' \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://{host}/lucca-api/employees"

headers = {
    "Api-Version": "<api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Api-Version': '<api-version>', Authorization: 'Bearer <token>'}
};

fetch('https://{host}/lucca-api/employees', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{host}/lucca-api/employees",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Api-Version: <api-version>",
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{host}/lucca-api/employees"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Api-Version", "<api-version>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{host}/lucca-api/employees")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Api-Version"] = '<api-version>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "instance": "https://example.ilucca.net/lucca-api/leaves/1573",
  "errors": {
    "endsOn": [
      "Invalid period: StartsOn should be before EndsOn."
    ],
    "employeeId": [
      "The employeeId query parameter is required."
    ]
  },
  "extensions": {
    "traceId": "|78777424-49cc27e04281bbfc."
  }
}

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "instance": "https://example.ilucca.net/lucca-api/employees/1573"
}

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Internal Server Error",
  "status": 500,
  "instance": "https://example.ilucca.net/lucca-api/employees/1573"
}

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 1,000. Read more about pagination.

Required range: 0 <= x <= 1000

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

Example:

["123", "456"]

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

Response

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

Show child attributes

links

Links · object | null

Links to related resources

Show child attributes

embedded

object | null

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

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

Show child attributes

Overview

Files

Organization

Employee Records

Time Management

Events & Webhooks

List employees

Authorizations

Headers

Query Parameters

Response