Retrieve an employee

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.

Path Parameters

string

required

Identifier of the employee to retrieve.

Minimum string length: 1

Query Parameters

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

An employee resource.

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

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

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

string

Minimum string length: 1

type

string

Allowed value: "employee"

url

string<uri>

remoteId

null | string

Must be unique.

Required string length: 1 - 100

portrait

portrait-reference · object

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

Show child attributes

portrait.id

string

required

Minimum string length: 1

portrait.type

string

Allowed value: "portrait"

portrait.url

string<uri>

employeeNumber

null | string

Required string length: 1 - 50

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

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

birthDay.day

integer<int32>

required

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

Required range: 1 <= x <= 31

birthDay.month

integer<int32>

required

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

Required range: 1 <= x <= 12

phoneNumber

string<phone> | null

Professional phone number of this employee.

Example:

"+3356565656"

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

applicableEmployment.id

string

Minimum string length: 1

applicableEmployment.type

string

Allowed value: "employment"

applicableEmployment.url

string<uri>

applicableJobPosition

object

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

Show child attributes

applicableJobPosition.id

string

Minimum string length: 1

applicableJobPosition.type

string

Allowed value: "job-position"

applicableJobPosition.url

string<uri>

createdAt

string<date-time-offset>

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

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.

links

object

Show child attributes

links.employments

Link · object

Object that represents an hyperlink.

Show child attributes

links.employments.href

string<uri>

required

URL to the related object.

links.jobPositions

Link · object

Object that represents an hyperlink.

Show child attributes

links.jobPositions.href

string<uri>

required

URL to the related object.

links.personalRecord

Link · object

Object that represents an hyperlink.

Show child attributes

links.personalRecord.href

string<uri>

required

URL to the related object.

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

Overview

Organization

Employee Records

Events & Webhooks

Retrieve an employee

Authorizations

Headers

Path Parameters

Query Parameters

Response