> ## 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. # Update employee-personal-record > Update an employee-personal-record. You cannot change the `employee.id` reference of an existing record (i.e. change the employee it belongs to). > [!WARNING] > > 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](https://developers.luccasoftware.com/documentation/using-api/versioning.md). > **Access** > > **OAuth 2.0 scopes** > > ``` > 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 patch /lucca-api/employee-personal-records/{id} openapi: 3.1.0 info: title: Lucca API reference version: '2024-11-01' x-revision: 7e1be45a2c75 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: events description: >- Major resources of the Lucca API are subject to events, which means every time their state changes (creation, update, deletion), an event is fired. These events are stored for a limited time (c.f. documentation), and can either be retrieved through the events endpoint, or they can be sent to your webhook-endpoint. - name: working-time-arrangements description: working-time-arrangements - name: files description: Files management. paths: /lucca-api/employee-personal-records/{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-personal-record to retrieve. in: path required: true schema: type: string patch: tags: - employees summary: Update employee-personal-record description: >- Update an employee-personal-record. You cannot change the `employee.id` reference of an existing record (i.e. change the employee it belongs to). operationId: patch-employee-personal-record requestBody: description: Representation of an employee-personal-record. content: application/json: schema: type: object unevaluatedProperties: false description: An employee-personal-record resource. allOf: - $ref: '#/components/schemas/employee-personal-record.update' examples: record: $ref: '#/components/examples/employee-personal-record.patch.example' 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: type: object unevaluatedProperties: false description: An employee-personal-record resource. allOf: - $ref: '#/components/schemas/employee-personal-record.read' examples: record: $ref: '#/components/examples/employee-personal-record.get.example' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' default: $ref: '#/components/responses/500' security: - 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). Includes the download links of the files the resource references, under `links.files`. - `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). Includes the download links of the files the resource references, under `links.files`. totalCount: >- Is only applicable on collections (i.e. lists of resources), gives the total number of items across all pages. schemas: employee-personal-record.update: allOf: - $ref: '#/components/schemas/employee-personal-record' - type: object properties: id: readOnly: true type: readOnly: true url: readOnly: true employee: readOnly: true createdAt: readOnly: true lastUpdatedAt: readOnly: true links: readOnly: true employee-personal-record.read: allOf: - $ref: '#/components/schemas/employee-personal-record' - $ref: '#/components/schemas/employee-personal-record.embedded' 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' maritalStatus: description: >- - `unknown`: Not indicated. Equivalent to a technical `null`. - `single`: Neither married nor in a civil partnership. - `civilPartner`: Non-religious legal partnership. French: 'PACS'. - `married`: Married. - `divorced`: Divorced. - `widowed`: Widowed. - `cohabitant`: Living with a partner without legal union. French: 'Concubinage'. type: string enum: - unknown - single - civilPartner - married - divorced - widowed - cohabitant default: unknown birthDate: type: - 'null' - string format: date pattern: ^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$ 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: idn-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 maritalStatus: single 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: {} 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](/api-reference/2024-11-01/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.' t9n: description: >- Translations of the problem. `t9n.detail` holds the translations of `detail`, indexed by language. type: object properties: detail: $ref: '#/components/schemas/t9n' example: type: https://tools.ietf.org/html/rfc7231#section-6.5.1 title: Bad Request detail: One or more validation errors occurred. status: 400 errors: startsOn: - 'Invalid period: startsOn should be before endsOn.' t9n: detail: fr-FR: Une (au moins) erreur de validation a été rencontrée. 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-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 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 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 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 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 accountIdentifier: '123456789' bankIdentifier: '021000021' phone: title: Phone number description: >- Phone number, in international or national format (e.g. "+33 1 23 45 67 89" or "01 23 45 67 89"). type: string maxLength: 50 pattern: ^[\s0-9+()-]{6,50}$ examples: - '+3356565656' - 01 23 45 67 89 createdAt: title: createdAt description: >- **Read-only.** UTC timestamp of the moment this object was created. The UTC offset may be written `Z` or `+00:00`, with up to 7 fractional digits of a second. type: string format: date-time examples: - '2023-01-23T12:45:23.1234567+00:00' - '2023-01-23T12:45:23.1234Z' lastUpdatedAt: title: lastUpdatedAt description: >- **Read-only.** UTC timestamp of the moment this object was last updated. Set upon creation, update or deletion of the object. The UTC offset may be written `Z` or `+00:00`, with up to 7 fractional digits of a second. type: string format: date-time examples: - '2023-01-23T12:45:23.1234567+00:00' - '2023-01-23T12:45:23.1234Z' 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](/api-reference/2024-11-01/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](/api-reference/2024-11-01/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: idn-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 mobile phone number of this employee. applicableEmployment: $ref: '#/components/schemas/employment-reference' description: >- **Read-only.** Reference to the applicable [employment](/api-reference/2024-11-01/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](/api-reference/2024-11-01/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' deprecated: true description: >- Link to the JSON representation of the `portrait` file, carrying its token. Use `links.files["{id}"]` instead, where `{id}` is the `portrait` id, which downloads the file content and tells when its token expires. files: $ref: '#/components/schemas/file-links' example: id: '416' type: employee url: https://example.ilucca.net/lucca-api/employees/416 remoteId: '00002345' portrait: id: 2face165-5345-4cf3-ab05-5421a6b19df2 type: portrait url: >- https://example.ilucca.net/lucca-api/portraits/2face165-5345-4cf3-ab05-5421a6b19df2 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/2face165-5345-4cf3-ab05-5421a6b19df2?token=eyXXXXXXXX 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 files: 2face165-5345-4cf3-ab05-5421a6b19df2: href: >- https://example.ilucca.net/lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2?token=eyXXXXXXXX&disposition=attachment expiresAt: '2026-10-21T15:01:38.7634288Z' token: eyXXXXXXXX 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' portrait-reference: title: portrait-reference description: >- Reference to a [portrait](/api-reference/2024-11-01/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](/api-reference/2024-11-01/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](/api-reference/2024-11-01/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](/api-reference/2024-11-01/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 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 file-links: title: file-links description: >- Download links to the files referenced by the resource, indexed by file id. Every object of type `file` in the resource has an entry here, whatever its depth, and one entry only — even when the same file is referenced several times. On a collection, each item holds the links to its own files. Returned with the other links of the resource, with `?include=links`. Requesting them mints one authorization token per file, so ask for them only when you intend to download. Follow each `href` with the same credentials you used to read the resource: the token it carries is bound to your API client and does not authenticate you on its own. type: object additionalProperties: $ref: '#/components/schemas/file-link' file-link: title: file-link description: >- A time-limited download link to a single file. The link does not replace your credentials: send the request with the same `Authorization` header you used to read the resource, and, with an OAuth access token, the `files.readonly` or `files.readwrite` scope. The token it carries authorizes your API client to access this one file; another client cannot use it, and without credentials the request fails with a `401`. `href` carries both the authorization token and an explicit `disposition`, so following it returns the file content whatever your `Accept` header, with the file name and content type in the `Content-Disposition` and `Content-Type` response headers. `null` when you may not download this file. type: - object - 'null' additionalProperties: false properties: href: type: string format: uri examples: - >- https://example.ilucca.net/lucca-api/files/9154c6a2-6105-4d5d-bfb6-5fd2d54037b3?token=eyXXXXXXXX&disposition=attachment description: >- Absolute URL to the file content, carrying the authorization token. Follow it with your own credentials. expiresAt: type: string format: date-time examples: - '2026-09-12T04:34:12.432Z' description: >- Instant past which `href` stops working. To obtain a fresh link, read the resource again with `?include=links`; do not store `href`. token: type: string minLength: 1 description: >- The authorization token carried by `href`, exposed on its own so you can build your own URL to the [file](/api-reference/2024-11-01/files/file) endpoint — for instance to request its JSON representation instead of its content. required: - href - expiresAt - token examples: employee-personal-record.patch.example: summary: employee-personal-record PATCH example description: employee-personal-record PATCH example value: phoneNumber: '+33456789634' email: jdoe13@gmail.com employee-personal-record.get.example: summary: employee-personal-record GET example description: employee-personal-record GET example value: 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 maritalStatus: single 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: {} embedded: employee: '416': id: '416' type: employee url: https://example.ilucca.net/lucca-api/employees/416 remoteId: '00002345' portrait: id: 2face165-5345-4cf3-ab05-5421a6b19df2 type: portrait url: >- https://example.ilucca.net/lucca-api/portraits/2face165-5345-4cf3-ab05-5421a6b19df2 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/2face165-5345-4cf3-ab05-5421a6b19df2?token=eyXXXXXXXX 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 files: 2face165-5345-4cf3-ab05-5421a6b19df2: href: >- https://example.ilucca.net/lucca-api/files/2face165-5345-4cf3-ab05-5421a6b19df2?token=eyXXXXXXXX&disposition=attachment expiresAt: '2026-10-21T15:01:38.7634288Z' token: eyXXXXXXXX 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' 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 '404': description: Not Found. Resource may have previously been deleted. 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: Not Found status: 404 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/2024-11-01/organization/legal-entity). legal-entities.readwrite: >- Create, update or delete [legal-entities](/api-reference/2024-11-01/organization/legal-entity). business-establishments.readonly: >- Read [business-establishments](/api-reference/2024-11-01/organization/business-establishment). business-establishments.readwrite: >- Create, update or delete [business-establishments](/api-reference/2024-11-01/organization/business-establishment). departments.readonly: >- Read [departments](/api-reference/2024-11-01/organization/department). departments.readwrite: >- Create, update or delete [departments](/api-reference/2024-11-01/organization/department). employees.readonly: Read [employees](/api-reference/2024-11-01/employees/employee). employees.readwrite: >- Create or update [employees](/api-reference/2024-11-01/employees/employee). employee-attribute-definitions.readonly: >- Read [employee-attribute-definitions](/api-reference/2024-11-01/employee-attributes/employee-attribute-definition). employee-attribute-definitions.readwrite: >- Create, update or delete [employee-attribute-definitions](/api-reference/2024-11-01/employee-attributes/employee-attribute-definition) and [taxonomies](/api-reference/2024-11-01/taxonomies/taxonomy). employee-attributes.readonly: >- Read [employee-attributes](/api-reference/2024-11-01/employee-attributes/employee-attribute). employee-attributes.readwrite: >- Create, update or delete [employee-attributes](/api-reference/2024-11-01/employee-attributes/employee-attribute). employee-personal-records.readonly: >- Read [employee-personal-records](/api-reference/2024-11-01/employees/employee-personal-record). 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/2024-11-01/employees/employee-personal-record). This contains highly sensitive data about the personal detail of the person. employments.readonly: >- Read [employments](/api-reference/2024-11-01/employments/employment). employments.readwrite: >- Create, update or delete [employments](/api-reference/2024-11-01/employments/employment). employment-templates.readonly: >- Read [employment-templates](/api-reference/2024-11-01/employments/employment-template). employment-templates.readwrite: >- Create, update or archive [employment-templates](/api-reference/2024-11-01/employments/employment-template). job-positions.readonly: >- Read [job-positions](/api-reference/2024-11-01/employments/job-position). job-positions.readwrite: >- Create, update or delete [job-positions](/api-reference/2024-11-01/employments/job-position). probationary-periods.readonly: >- Read [probationary-periods](/api-reference/2024-11-01/employments/probationary-period). probationary-periods.readwrite: >- Create, update or delete [probationary-periods](/api-reference/2024-11-01/employments/probationary-period). occupation-categories.readonly: >- Read [occupation-categories](/api-reference/2024-11-01/employee-occupation-categories/occupation-category). occupation-categories.readwrite: >- Create, update or delete [occupation-categories](/api-reference/2024-11-01/employee-occupation-categories/occupation-category). job-qualifications.readonly: >- Read [job-qualifications](/api-reference/2024-11-01/employee-job-qualifications/job-qualification) and [professions](/api-reference/2024-11-01/employee-job-qualifications/profession). job-qualifications.readwrite: >- Create, update or delete [job-qualifications](/api-reference/2024-11-01/employee-job-qualifications/job-qualification) and [professions](/api-reference/2024-11-01/employee-job-qualifications/profession). taxonomies.readonly: >- Read [taxonomies](/api-reference/2024-11-01/taxonomies/taxonomy) and [taxonomy-labels](/api-reference/2024-11-01/taxonomies/taxonomy-label). taxonomies.readwrite: >- Create, update or delete [taxonomies](/api-reference/2024-11-01/taxonomies/taxonomy) and [taxonomy-labels](/api-reference/2024-11-01/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. events.readonly: >- Read [events](/api-reference/2024-11-01/events/event). Only events of resources covered by the client's other scopes are returned (see [access control](/api-reference/2024-11-01/events/access-control)). 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](/api-reference/2024-11-01/organization/legal-entity) legal-entities.readwrite: criticality: medium resources: >- [legal-entity](/api-reference/2024-11-01/organization/legal-entity) business-establishments.readonly: criticality: low resources: >- [business-establishment](/api-reference/2024-11-01/organization/business-establishment) business-establishments.readwrite: criticality: medium resources: >- [business-establishment](/api-reference/2024-11-01/organization/business-establishment) departments.readonly: criticality: low resources: '[department](/api-reference/2024-11-01/organization/department)' departments.readwrite: criticality: medium resources: '[department](/api-reference/2024-11-01/organization/department)' employees.readonly: criticality: medium resources: '[employee](/api-reference/2024-11-01/employees/employee)' employees.readwrite: criticality: medium resources: '[employee](/api-reference/2024-11-01/employees/employee)' employee-attribute-definitions.readonly: criticality: low resources: >- [employee-attribute-definition](/api-reference/2024-11-01/employee-attributes/employee-attribute-definition) employee-attribute-definitions.readwrite: criticality: medium resources: >- [employee-attribute-definition](/api-reference/2024-11-01/employee-attributes/employee-attribute-definition), [taxonomy](/api-reference/2024-11-01/taxonomies/taxonomy) employee-attributes.readonly: criticality: medium resources: >- [employee-attribute](/api-reference/2024-11-01/employee-attributes/employee-attribute) employee-attributes.readwrite: criticality: medium resources: >- [employee-attribute](/api-reference/2024-11-01/employee-attributes/employee-attribute) employee-personal-records.readonly: criticality: high resources: >- [employee-personal-record](/api-reference/2024-11-01/employees/employee-personal-record) employee-personal-records.readwrite: criticality: high resources: >- [employee-personal-record](/api-reference/2024-11-01/employees/employee-personal-record) employments.readonly: criticality: medium resources: '[employment](/api-reference/2024-11-01/employments/employment)' employments.readwrite: criticality: medium resources: '[employment](/api-reference/2024-11-01/employments/employment)' employment-templates.readonly: criticality: medium resources: >- [employment-template](/api-reference/2024-11-01/employments/employment-template) employment-templates.readwrite: criticality: medium resources: >- [employment-template](/api-reference/2024-11-01/employments/employment-template) job-positions.readonly: criticality: low resources: >- [job-position](/api-reference/2024-11-01/employments/job-position) job-positions.readwrite: criticality: medium resources: >- [job-position](/api-reference/2024-11-01/employments/job-position) probationary-periods.readonly: criticality: medium resources: >- [probationary-period](/api-reference/2024-11-01/employments/probationary-period) probationary-periods.readwrite: criticality: medium resources: >- [probationary-period](/api-reference/2024-11-01/employments/probationary-period) occupation-categories.readonly: criticality: low resources: >- [occupation-category](/api-reference/2024-11-01/employee-occupation-categories/get-started) occupation-categories.readwrite: criticality: medium resources: >- [occupation-category](/api-reference/2024-11-01/employee-occupation-categories/get-started) job-qualifications.readonly: criticality: low resources: >- [job-qualification](/api-reference/2024-11-01/employee-job-qualifications/job-qualification) and [professions](/api-reference/2024-11-01/employee-job-qualifications/profession) job-qualifications.readwrite: criticality: medium resources: >- [job-qualification](/api-reference/2024-11-01/employee-job-qualifications/job-qualification) and [professions](/api-reference/2024-11-01/employee-job-qualifications/profession) taxonomies.readonly: criticality: low resources: >- [taxonomy](/api-reference/2024-11-01/taxonomies/taxonomy) & [taxonomy-label](/api-reference/2024-11-01/taxonomies/taxonomy-label) taxonomies.readwrite: criticality: medium resources: >- [taxonomy](/api-reference/2024-11-01/taxonomies/taxonomy) & [taxonomy-label](/api-reference/2024-11-01/taxonomies/taxonomy-label) webhook-endpoints.readonly: criticality: low resources: >- [webhook-endpoint](/api-reference/2024-11-01/webhooks/webhook-endpoint) webhook-endpoints.readwrite: criticality: medium resources: >- [webhook-endpoint](/api-reference/2024-11-01/webhooks/webhook-endpoint) webhook-deliveries.readonly: criticality: low resources: >- [webhook-delivery](/api-reference/2024-11-01/webhooks/webhook-delivery) & [webhook-delivery-attempt](/api-reference/2024-11-01/webhooks/webhook-delivery-attempt) webhook-deliveries.readwrite: criticality: medium resources: >- [webhook-delivery](/api-reference/2024-11-01/webhooks/webhook-delivery) & [webhook-delivery-attempt](/api-reference/2024-11-01/webhooks/webhook-delivery-attempt) events.readonly: criticality: medium resources: '[event](/api-reference/2024-11-01/events/event)' working-time-arrangements.readonly: criticality: low resources: >- [working-time-arrangement](/api-reference/2024-11-01/working-time-arrangements/working-time-arrangement) files.readonly: criticality: medium resources: '[file](/api-reference/2024-11-01/files/file)' files.readwrite: criticality: medium resources: '[file](/api-reference/2024-11-01/files/file)' ```` ## Related topics - [API lifecycle](https://developers.luccasoftware.com/api-reference/latest/lifecycle.md) - [Retrieve an employee-personal-record](https://developers.luccasoftware.com/api-reference/latest/employees/get-employee-personal-record.md) - [List employee-personal-records](https://developers.luccasoftware.com/api-reference/latest/employees/get-employee-personal-records.md) - [The employee-personal-record resource](https://developers.luccasoftware.com/api-reference/latest/employees/employee-personal-record.md) - [OAuth scopes](https://developers.luccasoftware.com/api-reference/latest/oauth-scopes.md)