List employments

Security: OAuth 2.0

Scopes:

- employments.readonly
- employments.readwrite

Business-establishments: This 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

string[]

Filter out employments on their IDs.

Maximum array length: 100

Minimum string length: 1

remoteId

string[]

Filter out employments on their remoteId.

Maximum array length: 100

Minimum string length: 1

employee.id

string[]

Filter out employments on their employee IDs.

Maximum array length: 100

Minimum string length: 1

legalEntity.id

string[]

Filter out employments on the legal-entity IDs.

Maximum array length: 100

Minimum string length: 1

template.id

string[]

Filter out employments on their employment-template IDs.

Maximum array length: 100

Minimum string length: 1

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

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.

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.

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.

Response

A collection of employment resources.

type

string

required

Allowed value: "employments"

url

string<uri>

required

items

employment · object[]

required

Paginated list of employment resources.

Maximum array length: 100

Show child attributes

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

items.legalEntity.id

string

required

Minimum string length: 1

items.legalEntity.type

enum<string>

Available options:

legal-entity

Allowed value: "legal-entity"

items.legalEntity.url

string<uri>

items.start

object

required

Show child attributes

items.start.date

string<date>

required

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

items.template

employment-template-reference · object

required

Reference to an employment-template resource.

Show child attributes

items.template.id

string

required

Minimum string length: 1

items.template.type

enum<string>

Available options:

employment-template

Allowed value: "employment-template"

items.template.url

string<uri>

items.id

string

Minimum string length: 1

items.type

string

Allowed value: "employment"

items.url

string<uri>

items.remoteId

null | string

Resource identifier in a third-party system.

Required string length: 1 - 200

items.employee

employee-reference · object

Reference to an employee resource.

Show child attributes

items.employee.id

string

required

Minimum string length: 1

items.employee.type

enum<string>

Available options:

employee

Allowed value: "employee"

items.employee.url

string<uri>

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

object

Show child attributes

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

items.document

file-reference · object

Reference to a file resource.

Show child attributes

items.document.id

string

required

Minimum string length: 1

items.document.type

enum<string>

Available options:

file

Allowed value: "file"

items.document.url

string<uri>

Example:

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

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

Link · object

Link to the related job-positions for this employment.

Show child attributes

items.links.jobPositions.href

string<uri>

required

URL to the related object.

items.links.probationaryPeriods

Link · object

Link to the related probationary-periods for this employment.

Show child attributes

items.links.probationaryPeriods.href

string<uri>

required

URL to the related object.

totalCount

integer<int64> | null

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

Required range: x >= 0

embedded

object

Show child attributes

embedded.employee

object

Dictionary of employees indexed by ID.

Show child attributes

embedded.employee.{key}

employee · object

The employee represents the public face of an employee in the system. Note that an employee can also represent a trainee, an intern, a contractor, etc...

The applicableEmployment property references the employee's employment that is:

currently in effect if the employee is "active".
will first be in effect if the employee has an employment starting in the future (either the first or a new one).
was last in effect if the employee is no longer employed and is not expected to be re-remployed in the future.

The applicableJobPosition property references the employee's job-position that matches the same logic.

Show child attributes

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

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

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

embedded.employee.{key}.id

string

Minimum string length: 1

embedded.employee.{key}.type

string

Allowed value: "employee"

embedded.employee.{key}.url

string<uri>

embedded.employee.{key}.remoteId

null | string

Must be unique.

Required string length: 1 - 100

embedded.employee.{key}.portrait

portrait-reference · object

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

Show child attributes

embedded.employee.{key}.portrait.id

string

required

Minimum string length: 1

embedded.employee.{key}.portrait.type

string

Allowed value: "portrait"

embedded.employee.{key}.portrait.url

string<uri>

embedded.employee.{key}.employeeNumber

null | string

Required string length: 1 - 50

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

embedded.employee.{key}.birthDay.day

integer<int32>

required

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

Required range: 1 <= x <= 31

embedded.employee.{key}.birthDay.month

integer<int32>

required

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

Required range: 1 <= x <= 12

embedded.employee.{key}.phoneNumber

string<phone> | null

Professional phone number of this employee.

Example:

"+3356565656"

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

embedded.employee.{key}.applicableEmployment.id

string

Minimum string length: 1

embedded.employee.{key}.applicableEmployment.type

string

Allowed value: "employment"

embedded.employee.{key}.applicableEmployment.url

string<uri>

embedded.employee.{key}.applicableJobPosition

object

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

Show child attributes

embedded.employee.{key}.applicableJobPosition.id

string

Minimum string length: 1

embedded.employee.{key}.applicableJobPosition.type

string

Allowed value: "job-position"

embedded.employee.{key}.applicableJobPosition.url

string<uri>

embedded.employee.{key}.createdAt

string<date-time-offset>

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

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

object

Show child attributes

embedded.employee.{key}.links.employments

Link · object

Object that represents an hyperlink.

Show child attributes

embedded.employee.{key}.links.employments.href

string<uri>

required

URL to the related object.

embedded.employee.{key}.links.jobPositions

Link · object

Object that represents an hyperlink.

Show child attributes

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

string<uri>

required

URL to the related object.

embedded.employee.{key}.links.personalRecord

Link · object

Object that represents an hyperlink.

Show child attributes

embedded.employee.{key}.links.personalRecord.href

string<uri>

required

URL to the related object.

Example:

{
  "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": "[email protected]",
  "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": {
    "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

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