Skip to main content
GET
/
lucca-api
/
employments
List employments
curl --request GET \
  --url https://{host}/lucca-api/employments \
  --header 'Api-Version: <api-version>' \
  --header 'Authorization: Bearer <token>'
{
  "type": "employments",
  "url": "https://example.ilucca.net/lucca-api/employments?limit=25",
  "totalCount": 483,
  "items": [
    {
      "id": "4561",
      "type": "employment",
      "url": "https://example.ilucca.net/lucca-api/employments/4561",
      "remoteId": "JOB#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"
        }
      }
    }
  ],
  "links": {
    "prev": null,
    "next": {
      "href": "https://example.ilucca.net/lucca-api/employments?page=!sdk87Sdh&limit=25"
    }
  },
  "embedded": {
    "employee": {
      "416": {
        "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="
          }
        }
      }
    }
  }
}
This API endpoint is in beta and may be subject to changes, including breaking changes, without prior notice.
OAuth 2.0 scopes
 employments.readonly
or
 employments.readwrite
EstablishmentsThis API endpoint will filter out results based on accessible business-establishments.You may only access employments belonging to 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

​
id
string[]

Filter out employments on their IDs.

Maximum array length: 100
Minimum string length: 1
Example:
["123", "456"]
​
remoteId
string[]

Filter out employments on their remoteId.

Maximum array length: 100
Minimum string length: 1
Example:
["E500944", "E500945"]
​
employee.id
string[]

Filter out employments on their employee IDs.

Maximum array length: 100
Minimum string length: 1
Example:
["123", "456"]
​
legalEntity.id
string[]

Filter out employments on the legal-entity IDs.

Maximum array length: 100
Minimum string length: 1
Example:
["1", "3"]
​
template.id
string[]

Filter out employments on their employment-template IDs.

Maximum array length: 100
Minimum string length: 1
Example:
["4", "6"]
​
start.date
string<date>

Filter out employments on their start.date (strict equality).

​
status
enum<string>

Filter out employments on their status. 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"

​
start.date.between
string<date-range>

Filter out employments on their start.date (range). 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--.."

​
end.date

Filter out employments on their end.date (strict equality).

​
end.date.between
string<date-range>

Filter out employments on their end.date (range). 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--.."

​
sort
enum<string>[]

Order results by instruction. Read more about sorting. Default: id.

Available options:
id,
-id,
start.date,
-start.date,
end.date,
-end.date
​
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
​
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 employment resources.

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

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

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

Paginated list of employment resources.

Maximum array length: 100
​
links
Links · object

Links to related resources

​
embedded
object

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

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