> ## 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. # Create an employment > Create an employment for a employee in a legal-entity. No two employments of a given employee may overlap. 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** ``` employments.readwrite job-positions.readwrite ``` *** **Establishments** This API endpoint will filter out results based on accessible business-establishments. **You may only access employments belonging to employees whose applicable business-establishments are accessible to you.** ## OpenAPI ````yaml /openapi-specs/lucca-api@2024-11-01.json post /lucca-api/employments openapi: 3.1.0 info: title: Lucca API reference version: '2024-11-01' x-revision: 14a8d8fdcddd 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/employments: 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' post: tags: - employments summary: Create an employment description: |- Create an employment for a employee in a legal-entity. No two employments of a given employee may overlap. operationId: post-employments requestBody: description: The employment, and its first job-position to create. content: application/json: schema: type: object unevaluatedProperties: false allOf: - $ref: '#/components/schemas/employment.create' examples: employment: $ref: '#/components/examples/employments.post.example' responses: '201': description: Created headers: Api-Version: $ref: '#/components/headers/api-version' Content-Encoding: $ref: '#/components/headers/content-encoding' Location: $ref: '#/components/headers/location' ETag: $ref: '#/components/headers/eTag' Deprecation: $ref: '#/components/headers/deprecation' Sunset: $ref: '#/components/headers/sunset' content: application/json: schema: type: object unevaluatedProperties: false description: The created employment resource. allOf: - $ref: '#/components/schemas/employment.read' examples: employment: $ref: '#/components/examples/employment.get.example' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' default: $ref: '#/components/responses/500' security: - oAuth: - employments.readwrite - job-positions.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. schemas: employment.create: 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: remoteId: type: - 'null' - string minLength: 1 maxLength: 200 description: Resource identifier in a third-party system. employee: title: employee-reference description: Reference to an employee resource. type: object additionalProperties: false properties: id: type: string minLength: 1 legalEntity: description: >- Reference to a legal-entity. It must be the legal-entity of the business-establishment of the first job-position, otherwise the API returns a `400`. allOf: - title: Reference to a legal-entity description: >- Reference to a [legal-entity](../organization/legal-entity) resource. type: object additionalProperties: false properties: id: type: string minLength: 1 required: - id start: type: object required: - date additionalProperties: false properties: date: description: Date of the first day (included) of this employment. type: string pattern: ^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$ 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}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$ format: date document: oneOf: - title: file-reference description: Reference to a [file](../files/file) resource. type: object additionalProperties: false properties: id: type: string minLength: 1 required: - id - type: 'null' template: title: employment-template-reference description: >- Reference to an [employment-template](../employments/employment-template) resource. type: object additionalProperties: false properties: id: type: string minLength: 1 required: - id firstJobPosition: 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: 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 businessEstablishment: title: business-establishment-reference description: >- Reference to a [business-establishment](../organization/business-establishment) resource. type: object additionalProperties: false properties: id: type: string minLength: 1 jobTitle: description: Short description of the job occupied by this employee. type: - 'null' - string maxLength: 1024 minLength: 1 jobQualification: oneOf: - title: job-qualification-reference description: >- Reference to a [job-qualification](../employee-occupations/job-qualification) resource. type: object additionalProperties: false properties: id: type: string minLength: 1 required: - id - type: 'null' manager: oneOf: - title: employee-reference description: Reference to an employee resource. type: object additionalProperties: false properties: id: type: string minLength: 1 - type: 'null' occupationCategory: oneOf: - title: occupation-category-reference description: >- Reference to an [occupation-category](../employee-occupations/occupation-category) resource. type: object additionalProperties: false properties: id: type: string minLength: 1 required: - id - type: 'null' workingTimeArrangement: oneOf: - title: working-time-arrangement-reference description: Reference to a working-time-arrangement resource. type: object additionalProperties: false properties: id: type: string minLength: 1 required: - id - type: 'null' department: title: department-reference description: >- Reference to a [department](../organization/department) resource. type: object additionalProperties: false properties: id: type: string minLength: 1 document: oneOf: - title: file-reference description: Reference to a [file](../files/file) resource. type: object additionalProperties: false properties: id: type: string minLength: 1 required: - id - type: 'null' t9n: type: object additionalProperties: false properties: jobTitle: $ref: '#/components/schemas/t9n' required: - businessEstablishment - department required: - employee - start - legalEntity - template - firstJobPosition employment.read: allOf: - $ref: '#/components/schemas/employment' - $ref: '#/components/schemas/employment.embedded' 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' 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}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$ 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}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$ 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 employment.embedded: type: object properties: embedded: description: |- Embeds the representation of resources related to the employment(s). Only returned if requested by the API client: `?include=embedded`. type: - object - 'null' additionalProperties: false properties: employee: description: >- Employees these are the employment(s) of (cf. `employment.employee`). Structured as a dictionary of [employees](../employees/employee) indexed by their ID. type: - object - 'null' additionalProperties: $ref: '#/components/schemas/employee' legal-entity: description: >- Legal-entities these employment(s) are signed with (cf. `employment.legalEntity`). Structured as a dictionary of [legal-entities](../organization/legal-entity) indexed by their ID. type: - object - 'null' additionalProperties: $ref: '#/components/schemas/legal-entity' job-position: description: >- Job-positions of these employment(s) (cf. `links.jobPositions`). Structured as a dictionary of [job-positions](../employments/job-position) indexed by their ID. type: - object - 'null' additionalProperties: $ref: '#/components/schemas/job-position' probationary-period: description: >- Probationary-periods of these employment(s) (cf. `links.probationaryPeriods`). Structured as a dictionary of [probationary-periods](../employments/probationary-period) indexed by their ID. type: - object - 'null' additionalProperties: $ref: '#/components/schemas/probationary-period' 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-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 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 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 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' 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 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: 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](../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 legal-entity: title: legal-entity description: >- Representation of a legal entity, i.e. an organization that is subject to legal responsibilities in a given jurisdiction (country). A legal-entity may be comprised of several [business-establishments](/api-reference/2024-11-01/organization/business-establishment) which represent geographically localized structures where the actual work is done. One of which is marked as the legal-entity headquarters. x-tags: - organization type: object properties: id: type: string minLength: 1 type: type: string const: legal-entity url: type: string format: uri legalName: description: '**Must be unique**. Legal name of the legal-entity.' type: string minLength: 1 maxLength: 255 remoteId: type: - 'null' - string minLength: 1 maxLength: 50 description: The third-party API ID of the matching object. isArchived: description: >- If this legal-entity is archived. Only possible if there are no more business-establishment attached. type: boolean countryCode: $ref: '#/components/schemas/country-code' currencyCode: $ref: '#/components/schemas/currency-code' taxIdentificationNumber: description: >- Identifier of the legal-entity in its local jurisdiction. - France: SIREN (Système d'identification du répertoire des entreprises) - Germany: SN (Steuernummer). - Spain: N.I.F (Número de Identificación Fiscal) type: - 'null' - object additionalProperties: false required: - format - value properties: format: type: string enum: - other - franceSIREN - spainNIF - germanySN value: type: string minLength: 1 industryCode: description: >- The industry (classification) code identifies the main type of activity of this legal-entity. - France: APE or NAF code. - Spain: CNAE. - Germany: WZ (Die Klassifikation der Wirtschaftszweige). - U.S.A.: NAICS (North American Industry Classification System). type: - 'null' - object additionalProperties: false required: - format - value properties: format: type: string enum: - other - franceAPE - spainCNAE - germanyWZ - usaNAICS value: type: string minLength: 1 createdAt: $ref: '#/components/schemas/createdAt' lastUpdatedAt: $ref: '#/components/schemas/lastUpdatedAt' lastArchivedAt: $ref: '#/components/schemas/lastArchivedAt' links: type: object additionalProperties: false properties: businessEstablishments: $ref: '#/components/schemas/link' example: id: '123' type: legal-entity url: https://example.ilucca.net/lucca-api/legal-entities/123 legalName: Lucca S.A.S. remoteId: LE:83.2938 isArchived: false countryCode: FRA currencyCode: EUR taxIdentificationNumber: format: franceSIREN value: '44163769100128' industryCode: format: franceAPE value: 7022Z createdAt: '2024-01-01T08:34:23.0001Z' lastUpdatedAt: '2024-01-01T08:34:23.0001Z' lastArchivedAt: null links: businessEstablishments: href: >- https://example.ilucca.net/lucca-api/business-establishments?legalEntity.id=123 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. The `startsOn` of the first job-position of an employment follows the employment `start.date`: change the employment start instead, as updating it directly returns a `400`. This should be considered "applicable" based on the related [employment](../employments/employment) business-establishment timezone. type: string pattern: ^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$ 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}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$ 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: {} probationary-period: title: probationary-period description: >- A probationary-period represents a period during which an employment's employee under scrutiny to find out if they are the right fit and have sufficient skills for the position. Only one probationary-period may be created for a single [employment](./employment). A probationary-period start date `startsOn` is read-only as it must always be equal to the related employment start date `start.date`. type: object properties: id: type: string minLength: 1 type: type: string const: probationary-period url: type: string format: uri employment: $ref: '#/components/schemas/employment-reference' description: >- The [employment](./employment) this probationary-period applies to. Cannot be modified once the probationary-period is created. startsOn: description: '**Read-only**. Equal to the related employment start date.' type: string pattern: ^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$ format: date endsOn: description: >- **Read-only**. End date of the probationary-period, equal to `extendedEndsOn` if not null, and `initialEndsOn` otherwise. type: string pattern: ^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$ format: date initialEndsOn: description: >- Initial end date of the probationary-period. **Required** upon creation. type: string pattern: ^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$ format: date extendedEndsOn: description: End date of the probationary-period in case it was extended. type: - 'null' - string pattern: ^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$ format: date createdAt: $ref: '#/components/schemas/createdAt' lastUpdatedAt: $ref: '#/components/schemas/lastUpdatedAt' links: type: object additionalProperties: false example: id: '8721' type: probationary-period url: https://example.ilucca.net/lucca-api/probationary-periods/8721 employment: id: '4561' type: employment url: https://example.ilucca.net/lucca-api/employments/4561 startsOn: '2024-02-01' endsOn: '2024-07-31' initialEndsOn: '2024-04-30' extendedEndsOn: '2024-07-31' createdAt: '2024-03-24T08:21:35.001Z' lastUpdatedAt: '2024-03-24T08:21:35.001Z' links: {} 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 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 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 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 currency-code: title: iso-4217 currency code description: ISO-4217 currency code type: string enum: - EUR - CHF - GBP - USD - CAD - JPY - BBD - XAF - AUD - PLN - STN - NOK - XBA - XBB - ADP - GWP - ITL - IEP - ILR - LUC - LUL - ROL - RUR - VEF - ZWN - DKK - PEN - XCD - XSU - TND - VUV - PEI - PLZ - ESA - BOB - KPW - MGA - OMR - RWF - SLL - SGD - XPF - RON - ZAL - ESP - VEB - VNC - BTN - CNY - SVC - HKD - LSL - MUR - ZAR - NZD - XAU - HRK - LAJ - BGN - GEL - KES - MNT - SHP - UAH - YUD - DJF - GTQ - ANG - BUK - FRF - MXP - NLG - UGW - YUN - BHD - CLF - ERN - GYD - PAB - XOF - XTS - ARP - LTT - MZM - PTE - CSD - ZMK - BZD - FKP - MXV - SBD - CHW - TWD - TTD - TRY - UYU - BEC - BEL - GRD - IDR - ZRZ - BYN - ISK - LRD - ARA - DDM - GHC - SDP - UAK - BSD - LAK - MDL - MZN - SSP - UYI - BYR - CSJ - GWE - LUF - HTG - KRW - QAR - NIC - SIT - SDG - CHC - AOA - PHP - WST - BAD - BRN - BRR - CYP - GNS - LTL - MTP - UYN - DZD - AWG - KYD - SYP - TZS - FIM - MVQ - SUR - USS - ZRN - KHR - CRC - INR - NIO - LKR - SRD - UYW - XAG - DEM - XFU - CVE - CLP - CDF - CUC - CHE - XBD - ALK - BGK - EEK - GEK - LVR - TRL - AZN - CZK - UGX - USN - XPT - BRB - BGL - LSM - PEH - UYP - XRE - BMD - BOV - BWP - BIF - DOP - KZT - RSD - ZMW - BEF - BRC - CSK - GQE - GHP - ISJ - LVL - TPE - UGS - XFO - MVR - PGK - AED - UZS - AYM - BOP - BGJ - SKK - AFN - KMF - GMD - IRR - ILS - KGS - NPR - SAR - VES - XXX - HRD - ROK - ALL - GNF - JOD - MWK - SEK - XPD - BRE - ECV - STD - TMM - CUP - MAD - NGN - AFA - ECS - PES - COU - KWD - LBP - ATS - BYB - ZWD - AMD - GIP - MKD - MYR - MXN - RUB - THB - TOP - TMT - ARY - XEU - ARS - ETB - XDR - IQD - XUA - NAD - PKR - TJS - YER - ZWL - AOK - RHD - YUM - BND - GHS - SOS - ZWR - BAM - COP - HUF - JMD - LYD - XBC - MLF - SDD - ZWC - EGP - SZL - MOP - MMK - VND - AON - MTL - MRO - MZE - SRG - YDD - BDT - BRL - FJD - HNL - MRU - PYG - SCR - AOR - AZM - GNE - ILP - MGF - ESB - TJR lastArchivedAt: type: - string - 'null' format: date-time description: >- **Read-only.** UTC timestamp of the moment this object was last archived through its `isArchived` property. The UTC offset may be written `Z` or `+00:00`, with up to 7 fractional digits of a second. examples: - '2023-01-23T12:45:23.1234567+00:00' - '2023-01-23T12:45:23.1234Z' 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 job-position-changed-attributes: title: job-position-changed-attributes description: List of attributes that can change for a job-position. type: string enum: - remoteId - businessEstablishment - jobTitle - jobQualification - manager - occupationCategory - workingTimeArrangement - department - document - notes examples: employments.post.example: summary: employment POST example description: employment POST example value: remoteId: EMPLOYMENT#4512-ac employee: id: '416' legalEntity: id: '123' start: date: '2024-01-01' end: null document: id: '74411' template: id: '4' firstJobPosition: remoteId: null businessEstablishment: id: '5' jobTitle: Developer jobQualification: id: '982' manager: id: '541' occupationCategory: id: '12' workingTimeArrangement: id: '23' department: id: '32' document: null employment.get.example: summary: employment GET example description: employment GET example value: id: '4561' type: employment url: https://example.ilucca.net/lucca-api/employments/4561 remoteId: EMPLOYMENT#4512-ac employee: id: '416' type: employee url: https://example.ilucca.net/lucca-api/employees/416 legalEntity: id: '123' type: legal-entity url: https://example.ilucca.net/lucca-api/legal-entities/123 status: active start: date: '2024-01-01' end: null document: id: '74411' type: file url: https://example.ilucca.net/lucca-api/files/74411 template: id: '4' type: employment-template url: https://example.ilucca.net/lucca-api/employment-templates/4 createdAt: '2024-04-15T23:12:54.0001Z' lastUpdatedAt: '2024-04-15T23:12:54.0001Z' links: jobPositions: href: >- https://example.ilucca.net/lucca-api/job-positions?employment.id=4561 probationaryPeriods: href: >- https://example.ilucca.net/lucca-api/probationary-periods?employment.id=4561 embedded: 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= 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 location: schema: type: string format: uri description: >- URL to the resource. Most often, the created resource from a POST request made to a collection path, e.g. `POST /lucca-api/employees`. 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 '403': description: You do not have the required oAuth scopes. 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: 403 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) and [taxonomies](/api-reference/latest/taxonomies/taxonomy). 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. events.readonly: >- Read [events](/api-reference/latest/events/event). Only events of resources covered by the client's other scopes are returned (see [access control](/api-reference/latest/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](./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), [taxonomy](./taxonomies/taxonomy) 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) events.readonly: criticality: medium resources: '[event](./events/event)' 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)' ```` ## Related topics - [API lifecycle](/api-reference/latest/lifecycle.md) - [Create an employee](/api-reference/latest/employees/post-employees.md) - [Create a job-position](/api-reference/latest/employments/post-job-positions.md) - [Create a probationary-period](/api-reference/latest/employments/post-probationary-period.md) - [OAuth scopes](/api-reference/latest/oauth-scopes.md)