> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve an employee
> Retrieve a single employee.
This API endpoint is in beta and may be subject to changes, including breaking changes (similarly to the legacy API endpoints), without prior notice. [Read more about versioning](/documentation/using-api/versioning).
**OAuth 2.0 scopes**
```
employees.readonly
```
or
```
employees.readwrite
```
***
**Establishments**
This API endpoint will filter out results based on accessible business-establishments.
**You may only access employees whose applicable business-establishments are accessible to you.**
## OpenAPI
````yaml /openapi-specs/lucca-api@2024-11-01.json get /lucca-api/employees/{id}
openapi: 3.1.0
info:
title: Lucca API reference
version: '2024-11-01'
description: Please refer to developers.luccasoftware.com.
contact:
name: API Support
url: https://www.luccasoftware.com
email: no-reply@luccasoftware.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{host}
description: Your Lucca account URL.
variables:
host:
default: example.ilucca.net
description: >-
The URL of your dedicated Lucca account: `{account}.{env}.{region}`.
Account reflects your company name. Env indicates the environment.
Region depends on your server location.
**Please, use your test or sandbox environments (and not your
production env.) for testing purposes.**
Environments:
- `ilucca`: production environment for customers.
- `ilucca-test`: test environment for customers.
- `ilucca-demo`: demo environment for prospects.
Regions:
- `.ch` for Swiss located accounts.
- `.net` for the others.
Regarding sandboxes, the pattern differs:
`https://{account}-{sandboxName}.sandbox.{server}.luccasoftware.com`,
where:
- `{sandboxName}` is automatically generated upon creation.
- `{server}` may be "eu1", "eu2" or "ch1".
security: []
tags:
- name: organization
description: Organization.
- name: employees
description: Employees.
- name: employments
description: Employments & job-positions.
- name: employee-occupation-categories
description: Employee occupations categories.
- name: employee-job-qualifications
description: Job qualifications & professions.
- name: employee-attributes
description: Employee-Attributes.
- name: taxonomies
description: Taxonomies & taxonomy-labels.
- name: webhooks
description: Webhooks.
- name: working-time-arrangements
description: working-time-arrangements
- name: files
description: Files management.
paths:
/lucca-api/employees/{id}:
parameters:
- $ref: '#/components/parameters/api-version'
- $ref: '#/components/parameters/if-none-match'
- $ref: '#/components/parameters/if-match'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/include'
- name: id
description: Identifier of the employee to retrieve.
in: path
required: true
schema:
type: string
minLength: 1
get:
tags:
- employees
summary: Retrieve an employee
description: Retrieve a single employee.
operationId: get-employee
responses:
'200':
description: OK
headers:
Api-Version:
$ref: '#/components/headers/api-version'
Content-Encoding:
$ref: '#/components/headers/content-encoding'
ETag:
$ref: '#/components/headers/eTag'
Deprecation:
$ref: '#/components/headers/deprecation'
Sunset:
$ref: '#/components/headers/sunset'
content:
application/json:
schema:
unevaluatedProperties: false
allOf:
- $ref: '#/components/schemas/employee.read'
- description: An employee resource.
examples:
edward:
$ref: '#/components/examples/employee.get.example'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
default:
$ref: '#/components/responses/500'
security:
- oAuth:
- employees.readonly
- oAuth:
- employees.readwrite
components:
parameters:
api-version:
name: Api-Version
in: header
description: Set the [API version](/documentation/using-api/versioning).
schema:
type: string
format: date
const: '2024-11-01'
enum:
- '2024-11-01'
maxLength: 10
examples:
- '2024-11-01'
required: true
if-none-match:
name: If-None-Match
in: header
description: >-
Only execute the request if current cached version of the resource does
not match the one given here.
schema:
type: string
examples:
- W/q5sd4w2x1c1gfdg
required: false
if-match:
name: If-Match
in: header
description: >-
Only execute the request if current cached version of the resource
matches the one given here. Useful to avoid concurrency conflicts.
schema:
type: string
examples:
- W/q5sd4w2x1c1gfdg
required: false
accept-encoding:
name: Accept-Encoding
description: List of compression algorithms you support.
in: header
schema:
type: string
examples:
unWeighted:
value: gzip, compress, br
weighted:
value: gzip;q=1.0, identity; q=0.5, *;q=0
include:
description: >-
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](/documentation/using-api/includes).
name: include
in: query
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- embedded
- links
- totalCount
x-enumDescriptions:
embedded: >-
Partial or complete representations of related resources (e.g. the
employee the resource belongs to).
links: >-
Link resources 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: >-
Is only applicable on collections (i.e. lists of resources), gives
the total number of items across all pages.
headers:
api-version:
description: Name (date of release) of the API version.
schema:
type: string
const: '2024-11-01'
examples:
- '2024-11-01'
maxLength: 10
required: true
content-encoding:
description: >-
HTTP representation header that lists the encodings and the order in
which they have been applied to the representation of the resource.
required: false
schema:
type: array
uniqueItems: true
items:
type: string
enum:
- gzip
- compress
- deflate
- br
examples:
gzip:
value:
- gzip
eTag:
description: Identifies the cached version of the resource.
schema:
type: string
examples:
- W/q5sd4w2x1c1gfdg
deprecation:
description: |
Signals the resource has been deprecated.
schema:
type: string
format: date
maxLength: 10
examples:
- '2024-01-01'
sunset:
description: >
The **Sunset** response header (see [RFC
8594](https://datatracker.ietf.org/doc/html/rfc8594)) indicates the
point in time at which this endpoint or resource will become
unavailable. The sunset value is a timestamp [RFC 9110 Section
5.6.7][rfc-9110-5.6.7] that usually points to the future. If a sunset
value points to the past, then the endpooint or resource must be
expected to become unavailable at any time.
As an API client, you should monitor the presence and value of all
**Sunset** headers and be ready to take counter measures.
schema:
type: string
format: date-time
examples:
- '2026-01-01T00:00:00Z'
schemas:
employee.read:
allOf:
- $ref: '#/components/schemas/employee'
- $ref: '#/components/schemas/employee.embedded'
employee:
title: employee
x-tags:
- Employees
description: >-
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](../employments/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](../employments/job-position) that matches the same logic.
type: object
properties:
id:
type: string
minLength: 1
type:
type: string
const: employee
url:
type: string
format: uri
remoteId:
description: Must be unique.
type:
- 'null'
- string
minLength: 1
maxLength: 100
portrait:
oneOf:
- $ref: '#/components/schemas/portrait-reference'
- type: 'null'
description: >-
Reference to the employee's portrait, which is a file (picture)
representing them.
givenName:
type: string
minLength: 1
maxLength: 255
description: >-
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.
familyName:
type: string
minLength: 1
maxLength: 255
description: >-
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.
employeeNumber:
type:
- 'null'
- string
minLength: 1
maxLength: 50
status:
$ref: '#/components/schemas/employee-status'
email:
description: >-
Professional email of this employee. "<" and ">" characters are
forbidden. Some domains are blacklisted and may thus result in 400
errors.
type:
- 'null'
- string
format: email
minLength: 3
maxLength: 255
birthDay:
description: >-
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...
type:
- 'null'
- object
properties:
day:
description: Starts at "1". Maximum depends on the month.
type: integer
format: int32
minimum: 1
maximum: 31
month:
description: Starts at "1" and goes up to "12" (included).
type: integer
format: int32
minimum: 1
maximum: 12
additionalProperties: false
required:
- day
- month
phoneNumber:
oneOf:
- $ref: '#/components/schemas/phone'
- type: 'null'
description: Professional phone number of this employee.
applicableEmployment:
$ref: '#/components/schemas/employment-reference'
description: >-
**Read-only.** Reference to the applicable
[employment](../employments/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.
applicableJobPosition:
$ref: '#/components/schemas/job-position-reference'
description: >-
**Read-only.** Reference to the active
[job-position](../employments/job-position) of this employee.
Matches the same logic as the "applicableEmployment".
createdAt:
$ref: '#/components/schemas/createdAt'
lastUpdatedAt:
$ref: '#/components/schemas/lastUpdatedAt'
links:
type: object
additionalProperties: false
properties:
employments:
$ref: '#/components/schemas/link'
jobPositions:
$ref: '#/components/schemas/link'
personalRecord:
$ref: '#/components/schemas/link'
portrait:
$ref: '#/components/schemas/link'
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: 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
employee.embedded:
type: object
properties:
embedded:
description: |-
Embeds the representation of resources related to the employee(s).
Only returned if requested by the API client: `?include=embedded`.
type:
- object
- 'null'
additionalProperties: false
properties:
employment:
type:
- object
- 'null'
description: >-
Applicable employments of employee(s) (cf.
`employee.applicableEmployment`).
Structured as a dictionary of
[employments](../employments/employment) indexed by their ID.
additionalProperties:
$ref: '#/components/schemas/employment'
job-position:
type:
- object
- 'null'
description: >-
Applicable job-positions of employee(s) (cf.
`employee.applicableJobPosition`).
Structured as a dictionary of
[job-positions](../employments/job-position) indexed by ID.
additionalProperties:
$ref: '#/components/schemas/job-position'
problem:
title: Problem
description: >-
Represents a "problem detail" as a way to carry machine-readable details
of errors in a HTTP response.
type: object
additionalProperties: true
properties:
type:
type:
- string
- 'null'
description: >-
Identifies the problem type. Points to a page containing a
human-readable documentation for the problem type.
example: https://tools.ietf.org/html/rfc7231#section-6.5.1
title:
type:
- string
- 'null'
description: 'A short, summary of the problem type (e.g.: Service Unavailable)'
example: Bad Request
status:
description: >-
The HTTP status code generated by the origin server for this
occurrence of the problem.
type:
- integer
- 'null'
format: int32
minimum: 100
maximum: 599
example: 400
detail:
description: >-
A human-readable explanation specific to this occurrence of the
problem.
type:
- string
- 'null'
example: One or more validation errors occurred.
errors:
type: object
additionalProperties:
type: array
items:
type: string
example:
startsOn:
- 'Invalid period: startsOn should be before endsOn.'
example:
type: https://tools.ietf.org/html/rfc7231#section-6.5.1
title: Bad Request
details: One or more validation errors occurred.
status: 400
errors:
startsOn:
- 'Invalid period: startsOn should be before endsOn.'
portrait-reference:
title: portrait-reference
description: Reference to a [portrait](../employees/portrait) resource.
type: object
additionalProperties: false
required:
- id
readOnly: true
properties:
id:
type: string
minLength: 1
readOnly: true
type:
type: string
const: portrait
readOnly: true
url:
type: string
format: uri
readOnly: true
employee-status:
title: employee-status
description: >-
**Read-only.** The employee status is calculated from the employee's
[employments](../employments/employment).
- 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.
type: string
enum:
- active
- upcoming
- deactivated
x-enumDescriptions:
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.
examples:
- active
phone:
title: Phone number
description: Phone number.
type: string
format: phone
pattern: ^[\+]?[(]?[0-9]{3}[)]?[-\s\.]?[0-9]{3}[-\s\.]?[0-9]{4,6}$
examples:
- '+3356565656'
employment-reference:
title: employment-reference
description: Reference to an [employment](../employments/employment) resource.
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
minLength: 1
type:
type: string
const: employment
enum:
- employment
url:
type: string
format: uri
job-position-reference:
title: job-position-reference
description: Reference to a [job-position](../employments/job-position) resource.
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
minLength: 1
type:
type: string
const: job-position
enum:
- job-position
readOnly: true
url:
type: string
format: uri
readOnly: true
createdAt:
title: createdAt
description: '**Read-only.** UTC timestamp of the moment this object was created.'
type: string
format: date-time-offset
examples:
- '2023-01-23T12:45:23.1234Z'
lastUpdatedAt:
title: createdAt
description: |-
**Read-only.** UTC timestamp of the moment this object was last updated.
Set upon creation, update or deletion of the object.
type: string
format: date-time
examples:
- '2023-01-23T12:45:23.1234Z'
link:
title: Link
description: Object that represents an hyperlink.
type:
- object
- 'null'
additionalProperties: false
properties:
href:
type: string
format: uri
description: URL to the related object.
required:
- href
employment:
title: employment
description: >-
The employment resource represents a relationship between an
[employee](../employees/employee) and a
[legal-entity](../organization/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](/api-reference/latest/employments/job-position) resource,
which references an employment. Over the course of his/her employment,
the employee may occupy several job-positions.
x-tags:
- employees
type: object
properties:
id:
type: string
minLength: 1
type:
type: string
const: employment
url:
type: string
format: uri
remoteId:
type:
- 'null'
- string
minLength: 1
maxLength: 200
description: Resource identifier in a third-party system.
employee:
$ref: '#/components/schemas/employee-reference'
legalEntity:
$ref: '#/components/schemas/legal-entity-reference'
description: >-
**Read-only**. Reference to a legal-entity. Inferred from the
business-establishment of its first job-position.
status:
$ref: '#/components/schemas/employee-status'
start:
type: object
required:
- date
additionalProperties: false
properties:
date:
description: Date of the first day (included) of this employment.
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
format: date
end:
type:
- 'null'
- object
additionalProperties: false
required:
- date
properties:
date:
description: >-
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.
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
format: date
document:
oneOf:
- $ref: '#/components/schemas/file-reference'
- type: 'null'
template:
$ref: '#/components/schemas/employment-template-reference'
createdAt:
$ref: '#/components/schemas/createdAt'
lastUpdatedAt:
$ref: '#/components/schemas/lastUpdatedAt'
links:
type: object
additionalProperties: false
properties:
document:
$ref: '#/components/schemas/link'
jobPositions:
$ref: '#/components/schemas/link'
description: >-
Link to the related [job-positions](../employments/job-position)
for this employment.
probationaryPeriods:
$ref: '#/components/schemas/link'
description: Link to the related probationary-periods for this employment.
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
job-position:
title: job-position
x-tags:
- Employees
description: >-
The job position represents a stage in an
[employee](../employees/employee)'s career during one of their
[employment](/api-reference/latest/employments/employment) in a given
[business-establishment](../organization/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.
type: object
properties:
id:
type: string
minLength: 1
type:
type: string
const: job-position
url:
type: string
format: uri
remoteId:
minLength: 1
maxLength: 1024
description: >-
Resource identifier in a third-party system. No unicity constraint:
two job-positions may have the same value.
type:
- 'null'
- string
employment:
$ref: '#/components/schemas/employment-reference'
employee:
$ref: '#/components/schemas/employee-reference'
description: '**Read-only.** Reference to the employment''s employee.'
status:
$ref: '#/components/schemas/employee-status'
startsOn:
description: >-
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](../employments/employment) business-establishment
timezone.
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
format: date
endsOn:
description: >-
**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](../employments/employment) business-establishment
timezone.
Must be greater or equal than StartsOn date.
type:
- 'null'
- string
pattern: ^\d{4}-\d{2}-\d{2}$
format: date
businessEstablishment:
$ref: '#/components/schemas/business-establishment-reference'
jobTitle:
description: Short description of the job occupied by this employee.
type:
- 'null'
- string
maxLength: 1024
minLength: 1
jobQualification:
oneOf:
- $ref: '#/components/schemas/job-qualification-reference'
- type: 'null'
manager:
oneOf:
- $ref: '#/components/schemas/employee-reference'
- type: 'null'
description: >-
Reference to another employee, who is considered to be this
employee's manager.
occupationCategory:
oneOf:
- $ref: '#/components/schemas/occupation-category-reference'
- type: 'null'
workingTimeArrangement:
oneOf:
- $ref: '#/components/schemas/working-time-arrangement-reference'
- type: 'null'
department:
$ref: '#/components/schemas/department-reference'
document:
oneOf:
- $ref: '#/components/schemas/file-reference'
- type: 'null'
notes:
type:
- 'null'
- string
maxLength: 500
description: Optional notes about this job-position change.
t9n:
type: object
additionalProperties: false
properties:
jobTitle:
$ref: '#/components/schemas/t9n'
updatedAttributes:
description: >-
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.
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/job-position-changed-attributes'
createdAt:
$ref: '#/components/schemas/createdAt'
lastUpdatedAt:
$ref: '#/components/schemas/lastUpdatedAt'
links:
type: object
properties:
document:
$ref: '#/components/schemas/link'
additionalProperties: false
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: {}
employee-reference:
title: employee-reference
description: Reference to an employee resource.
type: object
additionalProperties: false
properties:
id:
type: string
minLength: 1
type:
type: string
const: employee
url:
type: string
format: uri
legal-entity-reference:
title: Reference to a legal-entity
description: Reference to a [legal-entity](../organization/legal-entity) resource.
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
minLength: 1
type:
type: string
const: legal-entity
enum:
- legal-entity
readOnly: true
url:
type: string
format: uri
readOnly: true
file-reference:
title: file-reference
description: Reference to a [file](../files/file) resource.
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
minLength: 1
type:
type: string
const: file
readOnly: true
url:
type: string
format: uri
readOnly: true
employment-template-reference:
title: employment-template-reference
description: >-
Reference to an
[employment-template](../employments/employment-template) resource.
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
minLength: 1
type:
type: string
const: employment-template
enum:
- employment-template
readOnly: true
url:
type: string
format: uri
readOnly: true
business-establishment-reference:
title: business-establishment-reference
description: >-
Reference to a
[business-establishment](../organization/business-establishment)
resource.
type: object
additionalProperties: false
properties:
id:
type: string
minLength: 1
type:
type: string
const: business-establishment
url:
type: string
format: uri
job-qualification-reference:
title: job-qualification-reference
description: >-
Reference to a
[job-qualification](../employee-occupations/job-qualification) resource.
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
minLength: 1
type:
type: string
const: job-qualification
enum:
- job-qualification
readOnly: true
url:
type: string
format: uri
readOnly: true
occupation-category-reference:
title: occupation-category-reference
description: >-
Reference to an
[occupation-category](../employee-occupations/occupation-category)
resource.
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
minLength: 1
type:
type: string
const: occupation-category
enum:
- occupation-category
readOnly: true
url:
type: string
format: uri
readOnly: true
working-time-arrangement-reference:
title: working-time-arrangement-reference
description: Reference to a working-time-arrangement resource.
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
minLength: 1
type:
type: string
const: working-time-arrangement
enum:
- working-time-arrangement
readOnly: true
url:
type: string
format: uri
readOnly: true
department-reference:
title: department-reference
description: Reference to a [department](../organization/department) resource.
type: object
additionalProperties: false
properties:
id:
type: string
minLength: 1
type:
type: string
const: department
url:
type: string
format: uri
t9n:
type:
- object
- 'null'
title: Translations
description: >-
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.
properties:
de-DE:
description: German (Germany)
type:
- string
- 'null'
en-US:
description: English (United States of America)
type:
- string
- 'null'
en-GB:
description: English (Great Britain)
type:
- string
- 'null'
es-ES:
description: Spanish (Spain)
type:
- string
- 'null'
fr-FR:
description: French (France)
type:
- string
- 'null'
fr-CH:
description: French (Switzerland)
type:
- string
- 'null'
it-IT:
description: Italian (Italy)
type:
- string
- 'null'
nl-BE:
description: Dutch (Belgium)
type:
- string
- 'null'
nl-NL:
description: Dutch (Netherlands)
type:
- string
- 'null'
pt-PT:
description: Portuguese (Portugal)
type:
- string
- 'null'
job-position-changed-attributes:
title: job-position-changed-attributes
description: List of attributes that can change for a job-position.
type: string
enum:
- remoteId
- jobTitle
- jobQualification
- occupationCategory
- workingTimeArrangement
- department
examples:
employee.get.example:
summary: employee GET example
description: employee GET example
value:
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
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: {}
responses:
'400':
description: |-
Bad request. You may:
- (write requests) make sure the request body conforms with the expected schema.
- double check all required parameters are set.
headers:
Api-Version:
$ref: '#/components/headers/api-version'
Deprecation:
$ref: '#/components/headers/deprecation'
Sunset:
$ref: '#/components/headers/sunset'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/problem'
example:
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.'
'401':
description: You are not authenticated. Please refresh your token.
headers:
Api-Version:
$ref: '#/components/headers/api-version'
Deprecation:
$ref: '#/components/headers/deprecation'
Sunset:
$ref: '#/components/headers/sunset'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/problem'
example:
type: https://datatracker.ietf.org/doc/html/rfc7235#section-3.1
title: Unauthorized
status: 401
instance: https://example.ilucca.net/lucca-api/employees/1573
'500':
description: Internal server error.
headers:
Api-Version:
$ref: '#/components/headers/api-version'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/problem'
example:
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
securitySchemes:
oAuth:
type: oauth2
description: >-
The Lucca API implements the [oAuth 2](https://oauth.net/2/) protocol
with the
[client-credentials-flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).
Refer to RFC8725.
flows:
clientCredentials:
tokenUrl: https://accounts.world.luccasoftware.com/connect/token
scopes:
legal-entities.readonly: >-
Read
[legal-entities](/api-reference/latest/organization/legal-entity).
legal-entities.readwrite: >-
Create, update or delete
[legal-entities](/api-reference/latest/organization/legal-entity).
business-establishments.readonly: >-
Read
[business-establishments](/api-reference/latest/organization/business-establishment).
business-establishments.readwrite: >-
Create, update or delete
[business-establishments](/api-reference/latest/organization/business-establishment).
departments.readonly: Read [departments](/api-reference/latest/organization/department).
departments.readwrite: >-
Create, update or delete
[departments](/api-reference/latest/organization/department).
employees.readonly: Read [employees](/api-reference/latest/employees/employee).
employees.readwrite: >-
Create or update
[employees](/api-reference/latest/employees/employee).
employee-attribute-definitions.readonly: >-
Read
[employee-attribute-definitions](/api-reference/latest/employee-attributes/employee-attribute-definition).
employee-attribute-definitions.readwrite: >-
Create, update or delete
[employee-attribute-definitions](/api-reference/latest/employee-attributes/employee-attribute-definition).
employee-attributes.readonly: >-
Read
[employee-attributes](/api-reference/latest/employee-attributes/employee-attribute).
employee-attributes.readwrite: >-
Create, update or delete
[employee-attributes](/api-reference/latest/employee-attributes/employee-attribute).
employee-personal-records.readonly: >-
Read
[employee-personal-records](/api-reference/latest/employees/employee-personal-records).
This contains highly sensitive data about the personal detail of
the person.
employee-personal-records.readwrite: >-
Create, update or delete
[employee-personal-records](/api-reference/latest/employees/employee-personal-records).
This contains highly sensitive data about the personal detail of
the person.
employments.readonly: Read [employments](/api-reference/latest/employments/employment).
employments.readwrite: >-
Create, update or delete
[employments](/api-reference/latest/employments/employment).
employment-templates.readonly: >-
Read
[employment-templates](/api-reference/latest/employments/employment-template).
employment-templates.readwrite: >-
Create, update or archive
[employment-templates](/api-reference/latest/employments/employment-template).
job-positions.readonly: >-
Read
[job-positions](/api-reference/latest/employments/job-position).
job-positions.readwrite: >-
Create, update or delete
[job-positions](/api-reference/latest/employments/job-position).
probationary-periods.readonly: >-
Read
[probationary-periods](/api-reference/latest/employments/probationary-period).
probationary-periods.readwrite: >-
Create, update or delete
[probationary-periods](/api-reference/latest/employments/probationary-period).
occupation-categories.readonly: >-
Read
[occupation-categories](/api-reference/latest/employee-occupations/occupation-category).
occupation-categories.readwrite: >-
Create, update or delete
[occupation-categories](/api-reference/latest/employee-occupations/occupation-category).
job-qualifications.readonly: >-
Read
[job-qualifications](/api-reference/latest/employee-occupations/job-qualification)
and
[professions](/api-reference/latest/employee-occupations/profession).
job-qualifications.readwrite: >-
Create, update or delete
[job-qualifications](/api-reference/latest/employee-occupations/job-qualification)
and
[professions](/api-reference/latest/employee-occupations/profession).
taxonomies.readonly: >-
Read [taxonomies](/api-reference/latest/taxonomies/taxonomy) and
[taxonomy-labels](/api-reference/latest/taxonomies/taxonomy-label).
taxonomies.readwrite: >-
Create, update or delete
[taxonomies](/api-reference/latest/taxonomies/taxonomy) and
[taxonomy-labels](/api-reference/latest/taxonomies/taxonomy-label).
webhook-endpoints.readonly: Read webhook-endpoints.
webhook-endpoints.readwrite: Create and update webhook-endpoints.
webhook-deliveries.readonly: Read webhook-deliveries.
webhook-deliveries.readwrite: Send a ping event to a webhook-endpoint.
working-time-arrangements.readonly: Read working-time-arrangements.
files.readonly: Read files stored in Lucca.
files.readwrite: Upload a file to Lucca.
x-scope-metadata:
legal-entities.readonly:
criticality: low
resources: '[legal-entity](./organization/legal-entity)'
legal-entities.readwrite:
criticality: medium
resources: '[legal-entity](./organization/legal-entity)'
business-establishments.readonly:
criticality: low
resources: '[business-establishment](./organization/business-establishment)'
business-establishments.readwrite:
criticality: medium
resources: '[business-establishment](./organization/business-establishment)'
departments.readonly:
criticality: low
resources: '[department](./organization/department)'
departments.readwrite:
criticality: medium
resources: '[department](./organization/department)'
employees.readonly:
criticality: medium
resources: '[employee](./employees/employee)'
employees.readwrite:
criticality: medium
resources: '[employee](./employees/employee)'
employee-attribute-definitions.readonly:
criticality: low
resources: >-
[employee-attribute-definition](./employee-attributes/employee-attribute-definition)
employee-attribute-definitions.readwrite:
criticality: medium
resources: >-
[employee-attribute-definition](./employee-attributes/employee-attribute-definition)
employee-attributes.readonly:
criticality: medium
resources: '[employee-attribute](./employee-attributes/employee-attribute)'
employee-attributes.readwrite:
criticality: medium
resources: '[employee-attribute](./employee-attributes/employee-attribute)'
employee-personal-records.readonly:
criticality: high
resources: '[employee-personal-record](./employees/employee-personal-record)'
employee-personal-records.readwrite:
criticality: high
resources: '[employee-personal-record](./employees/employee-personal-record)'
employments.readonly:
criticality: medium
resources: '[employment](./employments/employment)'
employments.readwrite:
criticality: medium
resources: '[employment](./employments/employment)'
employment-templates.readonly:
criticality: medium
resources: '[employment-template](./employments/employment-template)'
employment-templates.readwrite:
criticality: medium
resources: '[employment-template](./employments/employment-template)'
job-positions.readonly:
criticality: low
resources: '[job-position](./employments/job-position)'
job-positions.readwrite:
criticality: medium
resources: '[job-position](./employments/job-position)'
probationary-periods.readonly:
criticality: medium
resources: '[probationary-period](./employments/probationary-period)'
probationary-periods.readwrite:
criticality: medium
resources: '[probationary-period](./employments/probationary-period)'
occupation-categories.readonly:
criticality: low
resources: >-
[occupation-category](./employee-occupation-categories/get-started)
occupation-categories.readwrite:
criticality: medium
resources: >-
[occupation-category](./employee-occupation-categories/get-started)
job-qualifications.readonly:
criticality: low
resources: >-
[job-qualification](./employee-job-qualifications/job-qualification)
and [professions](./employee-job-qualifications/profession)
job-qualifications.readwrite:
criticality: medium
resources: >-
[job-qualification](./employee-job-qualifications/job-qualification)
and [professions](./employee-job-qualifications/profession)
taxonomies.readonly:
criticality: low
resources: >-
[taxonomy](./taxonomies/taxonomy) &
[taxonomy-label](./taxonomies/taxonomy-label)
taxonomies.readwrite:
criticality: medium
resources: >-
[taxonomy](./taxonomies/taxonomy) &
[taxonomy-label](./taxonomies/taxonomy-label)
webhook-endpoints.readonly:
criticality: low
resources: '[webhook-endpoint](./webhooks/webhook-endpoint)'
webhook-endpoints.readwrite:
criticality: medium
resources: '[webhook-endpoint](./webhooks/webhook-endpoint)'
webhook-deliveries.readonly:
criticality: low
resources: >-
[webhook-delivery](./webhooks/webhook-delivery) &
[webhook-delivery-attempt](./webhooks/webhook-delivery-attempt)
webhook-deliveries.readwrite:
criticality: medium
resources: >-
[webhook-delivery](./webhooks/webhook-delivery) &
[webhook-delivery-attempt](./webhooks/webhook-delivery-attempt)
working-time-arrangements.readonly:
criticality: low
resources: >-
[working-time-arrangement](./working-time-arrangements/working-time-arrangement)
files.readonly:
criticality: medium
resources: '[file](./files/file)'
files.readwrite:
criticality: medium
resources: '[file](./files/file)'
````