> ## 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.
# List employee-personal-records
> Retrieve a paginated list of employee-personal-records.
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**
```
employee-personal-records.readonly
```
or
```
employee-personal-records.readwrite
```
***
**Establishments**
This API endpoint will filter out results based on accessible business-establishments.
**You may only access employee-personal-records belonging to employees whose applicable business-establishments are accessible to you.**
## OpenAPI
````yaml /openapi-specs/lucca-api@2024-11-01.json get /lucca-api/employee-personal-records
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/employee-personal-records:
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'
get:
tags:
- employees
summary: List employee-personal-records
description: Retrieve a paginated list of employee-personal-records.
operationId: get-employee-personal-records
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit1000'
- name: employee.id
description: Filter out personal-records on the employee IDs.
in: query
style: form
explode: false
schema:
type: array
maxItems: 100
uniqueItems: true
items:
type: string
minLength: 1
examples:
- - '123'
- '456'
- name: legalGender
description: Filter out personal-records on the employee legal gender.
in: query
style: form
explode: false
schema:
type: array
uniqueItems: true
maxItems: 100
items:
$ref: '#/components/schemas/legal-gender'
examples:
- - male
- female
- name: nationalitiesCountryCodes
description: >-
Only return employees who have at least one of the passed country
codes nationalities.
in: query
style: form
explode: false
schema:
type: array
uniqueItems: true
maxItems: 100
items:
$ref: '#/components/schemas/country-code'
examples:
- - FRA
- DEU
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-personal-records.read'
- description: An collection of employee-personal-record resources.
examples:
records:
$ref: '#/components/examples/employee-personal-records.get.example'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
default:
$ref: '#/components/responses/500'
security:
- oAuth:
- employee-personal-records.readonly
- oAuth:
- employee-personal-records.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.
page:
name: page
in: query
description: >-
Cursor of the page to retrieve. Read more about
[pagination](/documentation/using-api/paging).
schema:
type: string
examples:
one:
summary: Page with token '!w.SDijk23'
value: '!w.SDijk23'
limit1000:
name: limit
in: query
description: |-
Number of items per page. Defaults to 25. Maximum is 1,000.
Read more about [pagination](/documentation/using-api/paging).
schema:
type: integer
default: 25
minimum: 0
maximum: 1000
examples:
one:
summary: Retrieve 25 items.
value: 25
schemas:
legal-gender:
description: |-
"Unknown" is equivalent to "unspecified" or "null".
"Diverse" may be legally acknowledged in some countries (e.g. Germany).
type: string
enum:
- unknown
- male
- female
- diverse
default: unknown
examples:
- unknown
country-code:
title: Country Code
description: >-
Three letters ISO 3166-1 alpha-3 country code. Lucca uses
[restcountries.com](https://restcountries.com/) to map these codes to
the country names displayed in the UI.
type: string
format: iso-3166-alpha-3
minLength: 3
maxLength: 3
enum:
- FRA
- ESP
- DEU
- CHE
- ITA
- GBR
- USA
- BEL
- CAN
- AFG
- ALA
- ALB
- DZA
- ASM
- AND
- AGO
- AIA
- ATA
- ATG
- ARG
- ARM
- ABW
- AUS
- AUT
- AZE
- BHS
- BHR
- BGD
- BRB
- BLR
- BLZ
- BEN
- BMU
- BTN
- BOL
- BIH
- BWA
- BVT
- BRA
- VGB
- IOT
- BRN
- BGR
- BFA
- BDI
- KHM
- CMR
- CPV
- CYM
- CAF
- TCD
- CHL
- CHN
- HKG
- MAC
- CXR
- CCK
- COL
- COM
- COG
- COD
- COK
- CRI
- CIV
- HRV
- CUB
- CYP
- CZE
- DNK
- DJI
- DMA
- DOM
- ECU
- EGY
- SLV
- GNQ
- ERI
- EST
- ETH
- FLK
- FRO
- FJI
- FIN
- GUF
- PYF
- ATF
- GAB
- GMB
- GEO
- GHA
- GIB
- GRC
- GRL
- GRD
- GLP
- GUM
- GTM
- GGY
- GIN
- GNB
- GUY
- HTI
- HMD
- VAT
- HND
- HUN
- ISL
- IND
- IDN
- IRN
- IRQ
- IRL
- IMN
- ISR
- JAM
- JPN
- JEY
- JOR
- KAZ
- KEN
- KIR
- PRK
- KOR
- KWT
- KGZ
- LAO
- LVA
- LBN
- LSO
- LBR
- LBY
- LIE
- LTU
- LUX
- MKD
- MDG
- MWI
- MYS
- MDV
- MLI
- MLT
- MHL
- MTQ
- MRT
- MUS
- MYT
- MEX
- FSM
- MDA
- MCO
- MNG
- MNE
- MSR
- MAR
- MOZ
- MMR
- NAM
- NRU
- NPL
- NLD
- NCL
- NZL
- NIC
- NER
- NGA
- NIU
- NFK
- MNP
- NOR
- OMN
- PAK
- PLW
- PSE
- PAN
- PNG
- PRY
- PER
- PHL
- PCN
- POL
- PRT
- PRI
- QAT
- REU
- ROU
- RUS
- RWA
- BLM
- SHN
- KNA
- LCA
- MAF
- SXM
- SPM
- VCT
- WSM
- SMR
- STP
- SAU
- SEN
- SRB
- SYC
- SLE
- SGP
- SVK
- SVN
- SLB
- SOM
- ZAF
- SGS
- SSD
- LKA
- SDN
- SUR
- SJM
- SWZ
- SWE
- SYR
- TWN
- TJK
- TZA
- THA
- TLS
- TGO
- TKL
- TON
- TTO
- TUN
- TUR
- TKM
- TCA
- TUV
- UGA
- UKR
- ARE
- UMI
- URY
- UZB
- VUT
- VEN
- VNM
- VIR
- WLF
- ESH
- YEM
- ZMB
- ZWE
examples:
- FRA
- DEU
employee-personal-records.read:
allOf:
- $ref: '#/components/schemas/employee-personal-records'
- $ref: '#/components/schemas/employee-personal-record.embedded'
employee-personal-records:
title: employee-personal-records
description: >-
A collection of
[employee-personal-record](/api-reference/2024-11-01/employees/employee-personal-record)
objects.
allOf:
- type: object
properties:
type:
type: string
const: employee-personal-records
url:
type: string
format: uri
totalCount:
type:
- integer
- 'null'
format: int64
minimum: 0
description: >-
Total number of employee-personal-record resources across all
pages that satisfy query parameters.
items:
type: array
items:
$ref: '#/components/schemas/employee-personal-record'
maxItems: 100
- $ref: '#/components/schemas/collection.links'
employee-personal-record.embedded:
type: object
properties:
embedded:
description: >-
Embeds the representation of resources related to the
employee-personal-record(s).
Only returned if requested by the API client: `?include=embedded`.
type:
- object
- 'null'
additionalProperties: false
properties:
employee:
description: >-
Employees these are the personal-record(s) of (cf.
`employeePersonalRecord.employee`).
Structured as a dictionary of [employees](../employees/employee)
indexed by ID.
type:
- object
- 'null'
additionalProperties:
$ref: '#/components/schemas/employee'
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.'
employee-personal-record:
title: employee-personal-record
x-tags:
- employees
description: >-
The employee-personal-record resource represents the confidential
attributes of an
[employee](/api-reference/2024-11-01/employees/employee), i.e. sensitive
personal information about them which gives details of their background,
identity proofs, and qualifications.
type: object
properties:
id:
type: string
minLength: 1
type:
type: string
const: employee-personal-record
url:
type: string
format: uri
employee:
$ref: '#/components/schemas/employee-reference'
title:
description: |-
- `unknown`: Not indicated. Equivalent to a technical `null`.
- `mister`: Either married or unmarried man. French: 'Monsieur'.
- `miss`: Unmarried woman. French: 'Mademoiselle'.
type: string
enum:
- unknown
- mister
- miss
default: unknown
legalGender:
$ref: '#/components/schemas/legal-gender'
birthDate:
type:
- 'null'
- string
format: date
pattern: ^\d{4}-\d{2}-\d{2}$
insuranceNumber:
oneOf:
- $ref: '#/components/schemas/insurance-number'
- type: 'null'
nationalitiesCountryCodes:
description: Array of ISO 3166-1 alpha-3 country codes.
type: array
maxItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/country-code'
bankAccount:
oneOf:
- $ref: '#/components/schemas/bank-account'
- type: 'null'
phoneNumber:
description: Personal phone number of the employee.
oneOf:
- $ref: '#/components/schemas/phone'
- type: 'null'
email:
description: Personal email address of the employee.
type:
- 'null'
- string
format: email
minLength: 3
maxLength: 255
createdAt:
$ref: '#/components/schemas/createdAt'
lastUpdatedAt:
$ref: '#/components/schemas/lastUpdatedAt'
links:
type: object
additionalProperties: false
example:
id: '897'
type: employee-personal-record
url: https://example.ilucca.net/lucca-api/employee-personal-records/897
employee:
id: '416'
type: employee
url: https://example.ilucca.net/lucca-api/employees/416
title: mister
legalGender: male
birthDate: '1989-12-21'
insuranceNumber:
format: frenchSSN
value: 1760774865895 37
nationalitiesCountryCodes:
- FRA
bankAccount:
format: iban
bankName: BNP Paribas
accountIdentifier: FR7630006000011234567890189
bankIdentifier: null
phoneNumber: '+33456789634'
email: jdoe13@gmail.com
links: {}
collection.links:
type: object
properties:
links:
title: Links
description: Links to related resources
type:
- object
- 'null'
required:
- prev
- next
properties:
prev:
allOf:
- $ref: '#/components/schemas/link'
- description: Link to the previous page. Is `null` on the first page.
next:
allOf:
- $ref: '#/components/schemas/link'
- description: Link to the next page. Is `null` on the last page.
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-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
insurance-number:
title: insurance-number
description: >-
Validation depends on selected format. Value for "other" format is not
validated.
type: object
properties:
format:
type: string
enum:
- frenchSSN
- swissSSN
- other
value:
type: string
bank-account:
description: >-
Represents a bank account in any format, including IBAN, SWIFT, and
region-specific routing details.
type: object
additionalProperties: false
required:
- format
properties:
format:
type: string
enum:
- other
- iban
default: other
bankName:
type:
- 'null'
- string
description: Optional name of the bank.
minLength: 1
maxLength: 255
accountIdentifier:
type:
- 'null'
- string
description: >-
When format is `iban`, then an IBAN is expected. Otherwise, may be
any local / domestic bank account number.
minLength: 1
maxLength: 255
bankIdentifier:
type:
- 'null'
- string
description: >-
When format is `iban`, then `null` is expected, given that an IBAN
already identifies the bank establishment. Otherwise, may be any
local bank identifier / routing number or international SWIFT BIC
code.
minLength: 1
maxLength: 255
examples:
- format: iban
bankName: BNP Paribas
accountIdentifier: FR7630006000011234567890189
bankIdentifier: null
- format: other
bankName: JPMorgan Chase Bank
accountNumber: '123456789'
routingNumber: '021000021'
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'
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
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
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
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'
examples:
employee-personal-records.get.example:
summary: employee-personal-records GET example
description: employee-personal-records GET example
value:
type: employee-personal-records
url: >-
https://example.ilucca.net/lucca-api/employee-personal-records?page=qsdkuh&limit=25
items:
- id: '897'
type: employee-personal-record
url: https://example.ilucca.net/lucca-api/employee-personal-records/897
employee:
id: '416'
type: employee
url: https://example.ilucca.net/lucca-api/employees/416
title: mister
legalGender: male
birthDate: '1989-12-21'
insuranceNumber:
format: frenchSSN
value: 1760774865895 37
nationalitiesCountryCodes:
- FRA
bankAccount:
format: iban
bankName: BNP Paribas
accountIdentifier: FR7630006000011234567890189
bankIdentifier: null
phoneNumber: '+33456789634'
email: jdoe13@gmail.com
links: {}
totalCount: 203
links:
prev: null
next:
href: >-
https://example.ilucca.net/lucca-api/employee-personal-records?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=416
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)'
````