> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve an employee-attribute

> Retrieve a single employee-attribute by ID.

<Tip>Unlike other API endpoints, access to employee attributes depends not only on an OAuth scope but also on access to the “sections” of the HR directory. [Learn more on this page](/api-reference/latest/employee-attributes/get-started#access).</Tip>

<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](/documentation/using-api/versioning).</Warning>

<Accordion title="Access" icon="key">
  **OAuth 2.0 scopes**

  ```
   employee-attributes.readonly
  ```

  or

  ```
   employee-attributes.readwrite
  ```

  ***

  **Establishments**

  This API endpoint will filter out results based on accessible business-establishments.

  **You may only access employee-attributes of employees whose applicable business-establishments are accessible to you.**

  ***

  **Claims**

  This API endpoint will filter out results based on accessible claims.

  **Each employee-attribute is associated with specific an employee directory "section". You may only access employee-attributes attached to sections that are accessible to you.**
</Accordion>


## OpenAPI

````yaml /openapi-specs/lucca-api@2024-11-01.json get /lucca-api/employee-attributes/{id}
openapi: 3.1.0
info:
  title: Lucca API reference
  version: '2024-11-01'
  description: Please refer to developers.luccasoftware.com.
  contact:
    name: API Support
    url: https://www.luccasoftware.com
    email: no-reply@luccasoftware.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://{host}
    description: Your Lucca account URL.
    variables:
      host:
        default: example.ilucca.net
        description: >-
          The URL of your dedicated Lucca account: `{account}.{env}.{region}`.


          Account reflects your company name. Env indicates the environment.
          Region depends on your server location.


          **Please, use your test or sandbox environments (and not your
          production env.) for testing purposes.**


          Environments:

          - `ilucca`: production environment for customers.

          - `ilucca-test`: test environment for customers.

          - `ilucca-demo`: demo environment for prospects.


          Regions:

          - `.ch` for Swiss located accounts.

          - `.net` for the others.


          Regarding sandboxes, the pattern differs:
          `https://{account}-{sandboxName}.sandbox.{server}.luccasoftware.com`,
          where:

          - `{sandboxName}` is automatically generated upon creation.

          - `{server}` may be "eu1", "eu2" or "ch1".
security: []
tags:
  - name: organization
    description: Organization.
  - name: employees
    description: Employees.
  - name: employments
    description: Employments & job-positions.
  - name: employee-occupation-categories
    description: Employee occupations categories.
  - name: employee-job-qualifications
    description: Job qualifications & professions.
  - name: employee-attributes
    description: Employee-Attributes.
  - name: taxonomies
    description: Taxonomies & taxonomy-labels.
  - name: webhooks
    description: Webhooks.
  - name: working-time-arrangements
    description: working-time-arrangements
  - name: files
    description: Files management.
paths:
  /lucca-api/employee-attributes/{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
        in: path
        required: true
        description: Identifier of the employee-attribute.
        schema:
          type: string
          minLength: 1
    get:
      tags:
        - employee-attributes
      summary: Retrieve an employee-attribute
      description: >-
        Retrieve a single employee-attribute by ID.


        <Tip>Unlike other API endpoints, access to employee attributes depends
        not only on an OAuth scope but also on access to the “sections” of the
        HR directory. [Learn more on this
        page](/api-reference/latest/employee-attributes/get-started#access).</Tip>
      operationId: get-employee-attribute
      responses:
        '200':
          description: OK
          headers:
            Api-Version:
              $ref: '#/components/headers/api-version'
            Content-Encoding:
              $ref: '#/components/headers/content-encoding'
            ETag:
              $ref: '#/components/headers/eTag'
            Deprecation:
              $ref: '#/components/headers/deprecation'
            Sunset:
              $ref: '#/components/headers/sunset'
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                allOf:
                  - $ref: '#/components/schemas/employee-attribute.read'
                  - description: An [employee-attribute](./employee-attribute) resource.
              examples:
                employee-attribute:
                  $ref: '#/components/examples/employee-attribute.get.example'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        default:
          $ref: '#/components/responses/500'
      security:
        - oAuth:
            - employee-attributes.readonly
        - oAuth:
            - employee-attributes.readwrite
components:
  parameters:
    api-version:
      name: Api-Version
      in: header
      description: Set the [API version](/documentation/using-api/versioning).
      schema:
        type: string
        format: date
        const: '2024-11-01'
        enum:
          - '2024-11-01'
        maxLength: 10
        examples:
          - '2024-11-01'
      required: true
    if-none-match:
      name: If-None-Match
      in: header
      description: >-
        Only execute the request if current cached version of the resource does
        not match the one given here.
      schema:
        type: string
        examples:
          - W/q5sd4w2x1c1gfdg
      required: false
    if-match:
      name: If-Match
      in: header
      description: >-
        Only execute the request if current cached version of the resource
        matches the one given here. Useful to avoid concurrency conflicts.
      schema:
        type: string
        examples:
          - W/q5sd4w2x1c1gfdg
      required: false
    accept-encoding:
      name: Accept-Encoding
      description: List of compression algorithms you support.
      in: header
      schema:
        type: string
      examples:
        unWeighted:
          value: gzip, compress, br
        weighted:
          value: gzip;q=1.0, identity; q=0.5, *;q=0
    include:
      description: >-
        Include metadata:
          - `embedded`: the partial or complete representations of related resources 
            (e.g. the employee the resource belongs to).
          - `links`: links to related resources or actions (e.g. approving a leave-request).
            May be `null` when you do not have access to the resource (or action).
          - `totalCount`: only applicable on collections (i.e. lists of resources), gives
            the total number of items across all pages.

        Read more about [expanding
        responses](/documentation/using-api/includes).
      name: include
      in: query
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
            - embedded
            - links
            - totalCount
          x-enumDescriptions:
            embedded: >-
              Partial or complete representations of related resources (e.g. the
              employee the resource belongs to).
            links: >-
              Link resources to related resources or actions (e.g. approving a
              leave-request).

              May be `null` when you do not have access to the resource (or
              action).
            totalCount: >-
              Is only applicable on collections (i.e. lists of resources), gives
              the total number of items across all pages.
  headers:
    api-version:
      description: Name (date of release) of the API version.
      schema:
        type: string
        const: '2024-11-01'
        examples:
          - '2024-11-01'
        maxLength: 10
      required: true
    content-encoding:
      description: >-
        HTTP representation header that lists the encodings and the order in
        which they have been applied to the representation of the resource.
      required: false
      schema:
        type: array
        uniqueItems: true
        items:
          type: string
          enum:
            - gzip
            - compress
            - deflate
            - br
      examples:
        gzip:
          value:
            - gzip
    eTag:
      description: Identifies the cached version of the resource.
      schema:
        type: string
        examples:
          - W/q5sd4w2x1c1gfdg
    deprecation:
      description: |
        Signals the resource has been deprecated.
      schema:
        type: string
        format: date
        maxLength: 10
        examples:
          - '2024-01-01'
    sunset:
      description: >
        The **Sunset** response header (see [RFC
        8594](https://datatracker.ietf.org/doc/html/rfc8594)) indicates the
        point in time at which this endpoint or resource will become
        unavailable. The sunset value is a timestamp [RFC 9110 Section
        5.6.7][rfc-9110-5.6.7] that usually points to the future. If a sunset
        value points to the past, then the endpooint or  resource must be
        expected to become unavailable at any time.

        As an API client, you should monitor the presence and value of all
        **Sunset** headers  and be ready to take counter measures.
      schema:
        type: string
        format: date-time
        examples:
          - '2026-01-01T00:00:00Z'
  schemas:
    employee-attribute.read:
      allOf:
        - $ref: '#/components/schemas/employee-attribute'
        - $ref: '#/components/schemas/employee-attribute.embedded'
    employee-attribute:
      title: employee-attribute
      description: >-
        An employee-attribute represents a single property value of an employee
        or any of their directly related resources.


        It can be:

        - a property of the [employee](../employees/employee) resource;

        - a property of their [employment](../employments/employment) resources;

        - a property of their [job-position](../job-position/job-position)
        resource;

        - an extension property of any of these resources, either user-defined
        or application-defined.


        Such representation makes it possible to retrieve all attributes of an
        employee in a uniform manner.
      type: object
      properties:
        id:
          type: string
          minLength: 1
        type:
          type: string
          const: employee-attribute
        url:
          type: string
          format: uri
        definition:
          $ref: '#/components/schemas/employee-attribute-definition-reference'
        employee:
          $ref: '#/components/schemas/employee-reference'
        employment:
          oneOf:
            - $ref: '#/components/schemas/employment'
            - type: 'null'
        jobPosition:
          oneOf:
            - $ref: '#/components/schemas/job-position'
            - type: 'null'
        applicability:
          description: >-
            The time window during which this attribute value applies to the
            employee.


            When the attribute comes from a time-bounded resource (e.g.
            `employment`, `job-position`), then its applicability is directly
            dependent on the target resource start and end. 


            `start: null` must be interpreted as "since the beginning of time",
            and `end: null` as "until the end of time".


            If the attribute has no temporal dimension (e.g.
            `employee.givenName`, custom extensions), both the `start` and `end`
            are `null`. It must be interpreted as "applies indefinitely".


            The `applicability.asOf` query parameter can be used to filter by
            date.
          type:
            - 'null'
            - object
          additionalProperties: false
          properties:
            start:
              description: >-
                Inclusive lower bound. Null means no lower limit ("since the
                beginning of time").
              type:
                - 'null'
                - string
              format: date
              pattern: ^\d{4}-\d{2}-\d{2}$
            end:
              description: >-
                Inclusive upper bound. Null means no upper limit ("until the end
                of time").
              type:
                - 'null'
                - string
              format: date
              pattern: ^\d{4}-\d{2}-\d{2}$
        value:
          type:
            - 'null'
            - boolean
            - number
            - string
            - object
            - array
          items:
            type:
              - 'null'
              - boolean
              - number
              - string
              - object
        createdAt:
          $ref: '#/components/schemas/createdAt'
        lastUpdatedAt:
          $ref: '#/components/schemas/lastUpdatedAt'
        links:
          type: object
          additionalProperties: false
      example:
        id: '34879'
        type: employee-attribute
        url: https://example.ilucca.net/lucca-api/employee-attribute/34879
        definition:
          id: givenName
          type: employee-attribute-definition
          url: >-
            https://example.ilucca.net/lucca-api/employee-attribute-definitions/givenName
        employee:
          id: '416'
          type: employee
          url: https://example.ilucca.net/lucca-api/employees/416
        applicability: null
        value: John
        createdAt: '2014-04-12T09:43:52.432Z'
        lastUpdatedAt: '2014-04-12T09:43:52.432Z'
        links: {}
    employee-attribute.embedded:
      type: object
      properties:
        embedded:
          description: >-
            Embeds the representation of resources related to the
            employee-attribute(s).


            Only returned if requested by the API client: `?include=embedded`.
          type:
            - object
            - 'null'
          properties:
            employee-attribute-definitions:
              type:
                - object
                - 'null'
              description: >-
                The employee-attribute-definitions associated with the
                employee-attribute(s).


                Structured as a dictionary of
                [employee-attribute-definitions](../employee-attributes/employee-attribute-definition)
                indexed by their ID.
              additionalProperties:
                $ref: '#/components/schemas/employee-attribute-definition'
            taxonomy-label:
              type:
                - object
                - 'null'
              description: >-
                The taxonomy labels referenced by the employee-attribute(s).


                Structured as a dictionary of [taxonomy
                labels](../taxonomies/taxonomy-label) indexed by their ID.
              additionalProperties:
                $ref: '#/components/schemas/taxonomy-label'
    problem:
      title: Problem
      description: >-
        Represents a "problem detail" as a way to carry machine-readable details
        of errors in a HTTP response.
      type: object
      additionalProperties: true
      properties:
        type:
          type:
            - string
            - 'null'
          description: >-
            Identifies the problem type. Points to a page containing a
            human-readable documentation for the problem type.
          example: https://tools.ietf.org/html/rfc7231#section-6.5.1
        title:
          type:
            - string
            - 'null'
          description: 'A short, summary of the problem type (e.g.: Service Unavailable)'
          example: Bad Request
        status:
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          type:
            - integer
            - 'null'
          format: int32
          minimum: 100
          maximum: 599
          example: 400
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          type:
            - string
            - 'null'
          example: One or more validation errors occurred.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            startsOn:
              - 'Invalid period: startsOn should be before endsOn.'
      example:
        type: https://tools.ietf.org/html/rfc7231#section-6.5.1
        title: Bad Request
        details: One or more validation errors occurred.
        status: 400
        errors:
          startsOn:
            - 'Invalid period: startsOn should be before endsOn.'
    employee-attribute-definition-reference:
      title: employee-attribute-definition-reference
      type: object
      properties:
        id:
          type: string
          minLength: 1
        type:
          type: string
          const: employee-attribute-definition
          readOnly: true
        url:
          type: string
          format: uri
          readOnly: true
    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
    employment:
      title: employment
      description: >-
        The employment resource represents a relationship between an
        [employee](../employees/employee) and a
        [legal-entity](../organization/legal-entity) over a continuous period.
        It may actually represent a work contract, an internship agreement, a
        contractor's contract, etc...


        The actual job of the employee is defined through the
        [job-position](/api-reference/latest/employments/job-position) resource,
        which references an employment. Over the course of his/her employment,
        the employee may occupy several job-positions.
      x-tags:
        - employees
      type: object
      properties:
        id:
          type: string
          minLength: 1
        type:
          type: string
          const: employment
        url:
          type: string
          format: uri
        remoteId:
          type:
            - 'null'
            - string
          minLength: 1
          maxLength: 200
          description: Resource identifier in a third-party system.
        employee:
          $ref: '#/components/schemas/employee-reference'
        legalEntity:
          $ref: '#/components/schemas/legal-entity-reference'
          description: >-
            **Read-only**. Reference to a legal-entity. Inferred from the
            business-establishment of its first job-position.
        status:
          $ref: '#/components/schemas/employee-status'
        start:
          type: object
          required:
            - date
          additionalProperties: false
          properties:
            date:
              description: Date of the first day (included) of this employment.
              type: string
              pattern: ^\d{4}-\d{2}-\d{2}$
              format: date
        end:
          type:
            - 'null'
            - object
          additionalProperties: false
          required:
            - date
          properties:
            date:
              description: >-
                Date of the last day (included) of this employment. After this
                date, this employment is considered terminated.


                Leave `null` for permanent employments (as long as the employee
                is kept), and set the date of the last day in case of a
                fixed-term employment.


                EndsOn date must be greater or equal than StartsOn date.
              type: string
              pattern: ^\d{4}-\d{2}-\d{2}$
              format: date
        document:
          oneOf:
            - $ref: '#/components/schemas/file-reference'
            - type: 'null'
        template:
          $ref: '#/components/schemas/employment-template-reference'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        lastUpdatedAt:
          $ref: '#/components/schemas/lastUpdatedAt'
        links:
          type: object
          additionalProperties: false
          properties:
            document:
              $ref: '#/components/schemas/link'
            jobPositions:
              $ref: '#/components/schemas/link'
              description: >-
                Link to the related [job-positions](../employments/job-position)
                for this employment.
            probationaryPeriods:
              $ref: '#/components/schemas/link'
              description: Link to the related probationary-periods for this employment.
      example:
        id: '4561'
        type: employment
        url: https://example.ilucca.net/lucca-api/employments/4561
        remoteId: EMPLOYMENT#4512-ac
        employee:
          id: '416'
          type: employee
          url: https://example.ilucca.net/lucca-api/employees/416
        legalEntity:
          id: '123'
          type: legal-entity
          url: https://example.ilucca.net/lucca-api/legal-entities/123
        status: active
        start:
          date: '2024-01-01'
        end: null
        document:
          id: '74411'
          type: file
          url: https://example.ilucca.net/lucca-api/files/74411
        template:
          id: '4'
          type: employment-template
          url: https://example.ilucca.net/lucca-api/employment-templates/4
        createdAt: '2024-04-15T23:12:54.0001Z'
        lastUpdatedAt: '2024-04-15T23:12:54.0001Z'
        links:
          jobPositions:
            href: >-
              https://example.ilucca.net/lucca-api/job-positions?employment.id=4561
          probationaryPeriods:
            href: >-
              https://example.ilucca.net/lucca-api/probationary-periods?employment.id=4561
    job-position:
      title: job-position
      x-tags:
        - Employees
      description: >-
        The job position represents a stage in an
        [employee](../employees/employee)'s career during one of their
        [employment](/api-reference/latest/employments/employment) in a given
        [business-establishment](../organization/business-establishment).


        It therefore outlines the attributes of the person as a professional
        (qualifications) and their role in the company as well as who's their
        manager.
      type: object
      properties:
        id:
          type: string
          minLength: 1
        type:
          type: string
          const: job-position
        url:
          type: string
          format: uri
        remoteId:
          minLength: 1
          maxLength: 1024
          description: >-
            Resource identifier in a third-party system. No unicity constraint:
            two job-positions may have the same value.
          type:
            - 'null'
            - string
        employment:
          $ref: '#/components/schemas/employment-reference'
        employee:
          $ref: '#/components/schemas/employee-reference'
          description: '**Read-only.** Reference to the employment''s employee.'
        status:
          $ref: '#/components/schemas/employee-status'
        startsOn:
          description: >-
            Effective date of this job-position for this employee.


            Cannot be outside the range of the employment.


            This should be considered "applicable" based on the related
            [employment](../employments/employment) business-establishment
            timezone.
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          format: date
        endsOn:
          description: >-
            **Read-only.** End date (included) of this job-position
            effectiveness.


            Is calculated from the `startsOn` property of the closest next
            job-position, or the `endsOn` date of the parent employment.


            This should be considered "applicable" based on the related
            [employment](../employments/employment) business-establishment
            timezone.


            Must be greater or equal than StartsOn date.
          type:
            - 'null'
            - string
          pattern: ^\d{4}-\d{2}-\d{2}$
          format: date
        businessEstablishment:
          $ref: '#/components/schemas/business-establishment-reference'
        jobTitle:
          description: Short description of the job occupied by this employee.
          type:
            - 'null'
            - string
          maxLength: 1024
          minLength: 1
        jobQualification:
          oneOf:
            - $ref: '#/components/schemas/job-qualification-reference'
            - type: 'null'
        manager:
          oneOf:
            - $ref: '#/components/schemas/employee-reference'
            - type: 'null'
          description: >-
            Reference to another employee, who is considered to be this
            employee's manager.
        occupationCategory:
          oneOf:
            - $ref: '#/components/schemas/occupation-category-reference'
            - type: 'null'
        workingTimeArrangement:
          oneOf:
            - $ref: '#/components/schemas/working-time-arrangement-reference'
            - type: 'null'
        department:
          $ref: '#/components/schemas/department-reference'
        document:
          oneOf:
            - $ref: '#/components/schemas/file-reference'
            - type: 'null'
        notes:
          type:
            - 'null'
            - string
          maxLength: 500
          description: Optional notes about this job-position change.
        t9n:
          type: object
          additionalProperties: false
          properties:
            jobTitle:
              $ref: '#/components/schemas/t9n'
        updatedAttributes:
          description: >-
            List of attributes that changed compared with this employee previous
            job-position, even if said job-position was on another employment
            and/or not immediately sequential.
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/job-position-changed-attributes'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        lastUpdatedAt:
          $ref: '#/components/schemas/lastUpdatedAt'
        links:
          type: object
          properties:
            document:
              $ref: '#/components/schemas/link'
          additionalProperties: false
      example:
        id: '74'
        type: job-position
        url: https://example.ilucca.net/lucca-api/job-positions/74
        remoteId: null
        employment:
          id: '28'
          type: employment
          url: https://example.ilucca.net/lucca-api/employments/28
        employee:
          id: '416'
          type: employee
          url: https://example.ilucca.net/lucca-api/employees/416
        status: active
        startsOn: '2024-01-01'
        endsOn: null
        businessEstablishment:
          id: '5'
          type: business-establishment
          url: https://example.ilucca.net/lucca-api/business-establishments/5
        jobTitle: Developer
        jobQualification:
          id: '982'
          type: job-qualification
          url: https://example.ilucca.net/lucca-api/job-qualifications/982
        manager:
          id: '541'
          type: employee
          url: https://example.ilucca.net/lucca-api/employees/541
        occupationCategory:
          id: '12'
          type: occupation-category
          url: https://example.ilucca.net/lucca-api/occupation-categories/12
        workingTimeArrangement:
          id: '23'
          type: working-time-arrangement
          url: about:blank
        department:
          id: '32'
          type: department
          url: https://example.ilucca.net/lucca-api/departments/32
        document: null
        notes: null
        t9n:
          jobTitle:
            fr-FR: Développeur
        updatedAttributes:
          - jobTitle
          - jobQualification
        createdAt: '2024-04-15T23:12:54.0001Z'
        lastUpdatedAt: '2024-04-15T23:12:54.0001Z'
        links: {}
    createdAt:
      title: createdAt
      description: '**Read-only.** UTC timestamp of the moment this object was created.'
      type: string
      format: date-time-offset
      examples:
        - '2023-01-23T12:45:23.1234Z'
    lastUpdatedAt:
      title: createdAt
      description: |-
        **Read-only.** UTC timestamp of the moment this object was last updated.
        Set upon creation, update or deletion of the object.
      type: string
      format: date-time
      examples:
        - '2023-01-23T12:45:23.1234Z'
    employee-attribute-definition:
      title: employee-attribute-definition
      description: employee-attribute-definition
      allOf:
        - $ref: '#/components/schemas/extension-definition'
        - $ref: '#/components/schemas/extension-definition-multiple-value-handling'
        - type: object
          properties:
            type:
              type: string
              const: employee-attribute-definition
            targetType:
              type: string
              enum:
                - employee
                - employment
                - job-position
      example:
        summary: employee-attribute-definition example
        description: employee-attribute-definition example
        value:
          id: e_tShirtSize
          type: employee-attribute-definition
          url: >-
            https://example.ilucca.net/lucca-api/employee-attribute-definitions/12
          name: T-shirt size
          multipleValueHandling: null
          schema:
            $id: /lucca-api/schemas/taxonomy-label-reference
            $schema: https://json-schema.org/draft/2020-12/schema
            title: taxonomy-label-reference
            type:
              - object
              - 'null'
            additionalProperties: false
            required:
              - id
            properties:
              id:
                type: string
                minLength: 1
              type:
                type: string
                const: taxonomy-label
                readOnly: true
              url:
                type: string
                format: uri
                readOnly: true
          taxonomy:
            id: '45'
            type: taxonomy
            url: https://example.ilucca.net/lucca-api/taxonomies/45
          t9n:
            name:
              fr-FR: Taille de t-shirt
          targetType: employee
          links: {}
    taxonomy-label:
      title: taxonomy-label
      description: >-
        Represents a label of a taxonomy, which is used to classify resources
        (e.g. employees).
      type: object
      properties:
        id:
          type: string
          minLength: 1
        type:
          type: string
          const: taxonomy-label
        url:
          type: string
          format: uri
        taxonomy:
          $ref: '#/components/schemas/taxonomy-reference'
        name:
          type: string
          minLength: 1
        remoteId:
          type:
            - 'null'
            - string
          minLength: 1
        applicabilitySchema:
          description: >-
            JSON schema of the applicable resources this taxonomy label only
            applies to.
          type:
            - 'null'
            - object
        createdAt:
          $ref: '#/components/schemas/createdAt'
        lastUpdatedAt:
          $ref: '#/components/schemas/lastUpdatedAt'
        isArchived:
          $ref: '#/components/schemas/isArchived'
        lastArchivedAt:
          $ref: '#/components/schemas/lastArchivedAt'
        t9n:
          type: object
          additionalProperties: false
          properties:
            name:
              $ref: '#/components/schemas/t9n'
        links:
          type: object
          additionalProperties: false
      example:
        id: '984'
        type: taxonomy-label
        url: https://example.ilucca.net/lucca-api/taxonomy-labels/984
        taxonomy:
          id: '45'
          type: taxonomy
          url: https://example.ilucca.net/lucca-api/taxonomies/45
        name: XL
        remoteId: tshirtSize.extraLarge
        createdAt: '2025-01-23T19:45:23Z'
        lastUpdatedAt: '2025-01-23T19:45:23Z'
        isArchived: false
        lastArchivedAt: null
        t9n: {}
        links: {}
    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
    link:
      title: Link
      description: Object that represents an hyperlink.
      type:
        - object
        - 'null'
      additionalProperties: false
      properties:
        href:
          type: string
          format: uri
          description: URL to the related object.
      required:
        - href
    employment-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
    business-establishment-reference:
      title: business-establishment-reference
      description: >-
        Reference to a
        [business-establishment](../organization/business-establishment)
        resource.
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          minLength: 1
        type:
          type: string
          const: business-establishment
        url:
          type: string
          format: uri
    job-qualification-reference:
      title: job-qualification-reference
      description: >-
        Reference to a
        [job-qualification](../employee-occupations/job-qualification) resource.
      type: object
      additionalProperties: false
      required:
        - id
      properties:
        id:
          type: string
          minLength: 1
        type:
          type: string
          const: job-qualification
          enum:
            - job-qualification
          readOnly: true
        url:
          type: string
          format: uri
          readOnly: true
    occupation-category-reference:
      title: occupation-category-reference
      description: >-
        Reference to an
        [occupation-category](../employee-occupations/occupation-category)
        resource.
      type: object
      additionalProperties: false
      required:
        - id
      properties:
        id:
          type: string
          minLength: 1
        type:
          type: string
          const: occupation-category
          enum:
            - occupation-category
          readOnly: true
        url:
          type: string
          format: uri
          readOnly: true
    working-time-arrangement-reference:
      title: working-time-arrangement-reference
      description: Reference to a working-time-arrangement resource.
      type: object
      additionalProperties: false
      required:
        - id
      properties:
        id:
          type: string
          minLength: 1
        type:
          type: string
          const: working-time-arrangement
          enum:
            - working-time-arrangement
          readOnly: true
        url:
          type: string
          format: uri
          readOnly: true
    department-reference:
      title: department-reference
      description: Reference to a [department](../organization/department) resource.
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          minLength: 1
        type:
          type: string
          const: department
        url:
          type: string
          format: uri
    t9n:
      type:
        - object
        - 'null'
      title: Translations
      description: >-
        Used for translation purposes. Object is structured as a dictionary
        whose keys refer to translated properties of the parent object, and
        whose values are a dictionary of supported languages.


        On the parent object, the translated property value is considered the
        "invariant" translation. It is expected to show this value whenever the
        user's language has no translation in `t9n`.


        Languages are identified through their RFC 4646 language tag.
      properties:
        de-DE:
          description: German (Germany)
          type:
            - string
            - 'null'
        en-US:
          description: English (United States of America)
          type:
            - string
            - 'null'
        en-GB:
          description: English (Great Britain)
          type:
            - string
            - 'null'
        es-ES:
          description: Spanish (Spain)
          type:
            - string
            - 'null'
        fr-FR:
          description: French (France)
          type:
            - string
            - 'null'
        fr-CH:
          description: French (Switzerland)
          type:
            - string
            - 'null'
        it-IT:
          description: Italian (Italy)
          type:
            - string
            - 'null'
        nl-BE:
          description: Dutch (Belgium)
          type:
            - string
            - 'null'
        nl-NL:
          description: Dutch (Netherlands)
          type:
            - string
            - 'null'
        pt-PT:
          description: Portuguese (Portugal)
          type:
            - string
            - 'null'
    job-position-changed-attributes:
      title: job-position-changed-attributes
      description: List of attributes that can change for a job-position.
      type: string
      enum:
        - remoteId
        - jobTitle
        - jobQualification
        - occupationCategory
        - workingTimeArrangement
        - department
    extension-definition:
      title: extension-definition
      description: extension-definition
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^\w{1,255}
          description: Client-generated identifier.
        type:
          type: string
        url:
          type: string
          format: uri
        name:
          type: string
          minLength: 1
        schema:
          description: >-
            JSON schema of the extension value. [Read more about extension
            definition
            schemas](/api-reference/latest/extension-definition-schemas).


            When creating a new extension definition, you must express its
            schema via referencing base schemas, e.g.:

            ```json

            {
              "schema": {
                "$ref": "/lucca-api/schemas/taxonomy-label-reference"
              }
            }

            ```


            The server responses will replace it by embedding the referenced
            JSON schema:

            ```json

            {
              "schema": {
                "$id": "/lucca-api/schemas/taxonomy-label-reference",
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "title": "taxonomy-label-reference",
                "type": ["object", "null"],
                "additionalProperties": false,
                "required": ["id"],
                "properties": {
                    "id": {
                        "type": "string",
                        "minLength": 1
                    },
                    "type": {
                        "type": "string",
                        "const": "taxonomy-label",
                        "readOnly": true
                    },
                    "url": {
                        "type": "string",
                        "format": "uri",
                        "readOnly": "true"
                    }
                }
              }
            }

            ```
          type: object
        propertyDescriptions:
          type:
            - object
            - 'null'
          description: >-
            Required whenever this definition schema is of type "object". 

            This property is a dictionary whose keys are the name of the schema
            object properties.
          additionalProperties:
            type: object
            required:
              - name
              - sortOrder
            properties:
              name:
                type: string
                minLength: 1
              taxonomy:
                anyOf:
                  - $ref: '#/components/schemas/taxonomy-reference'
                  - type: 'null'
              sortOrder:
                type: integer
                minimum: 0
              t9n:
                type: object
                additionalProperties: false
                properties:
                  name:
                    $ref: '#/components/schemas/t9n'
        taxonomy:
          description: >-
            Whenever the expected schema is a taxonomy-label reference, then the
            taxonomy these labels must belong to must be indicated.
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/taxonomy-reference'
        isArchived:
          $ref: '#/components/schemas/isArchived'
        lastArchivedAt:
          $ref: '#/components/schemas/lastArchivedAt'
        t9n:
          type: object
          additionalProperties: false
          properties:
            name:
              $ref: '#/components/schemas/t9n'
        links:
          type:
            - object
            - 'null'
    extension-definition-multiple-value-handling:
      type: object
      properties:
        multipleValueHandling:
          description: >-
            Behavior regarding multiple extension values per single extended
            resource. When `null`, then only a single extension can exist for
            any extended resource. Multiple extensions may be accepted
            otherwise.


            Example: "employee's children" would accept multiple value, when
            "employee's blood type" would not.
          type:
            - object
            - 'null'
          required:
            - sorting
          properties:
            sorting:
              description: >-
                In case of multiple extensions per resource, how should the
                client sort them (direction)?
              type: string
              enum:
                - ascending
                - descending
            sortingProperty:
              description: >-
                Not null for "object" schemas, in which case it points to the
                object property clients should sort extensions on:
                `extension.value[{sortingProperty}]`.

                Null otherwise, in which case clients are expected to sort on
                the actual `extension.value`.
              type:
                - string
                - 'null'
    taxonomy-reference:
      title: taxonomy-reference
      description: Reference to a taxonomy.
      type: object
      additionalProperties: false
      required:
        - id
      properties:
        id:
          type: string
          minLength: 1
        type:
          type: string
          const: taxonomy
          readOnly: true
        url:
          type: string
          format: uri
          readOnly: true
    isArchived:
      type: boolean
      description: |-
        When false, resource is not archived.
        When true, resource is archived.

        You can update this property in order to set the
        archival status of the resource.
    lastArchivedAt:
      type:
        - string
        - 'null'
      format: date-time
      description: >-
        **Read-only.** UTC timestamp of the moment this object was last archived
        through its `isArchived` property.
      examples:
        - '2023-01-23T12:45:23.1234Z'
  examples:
    employee-attribute.get.example:
      summary: employee-attribute GET example
      description: employee-attribute GET example
      value:
        id: '34879'
        type: employee-attribute
        url: https://example.ilucca.net/lucca-api/employee-attribute/34879
        definition:
          id: employee.givenName
          type: employee-attribute-definition
          url: >-
            https://example.ilucca.net/lucca-api/employee-attribute-definitions/employee.givenName
        employee:
          id: '416'
          type: employee
          url: https://example.ilucca.net/lucca-api/employees/416
        applicability: null
        value: John
        createdAt: '2014-04-12T09:43:52.432Z'
        lastUpdatedAt: '2014-04-12T09:43:52.432Z'
        links: {}
        embedded:
          employee-attribute-definition:
            givenName:
              id: employee.givenName
              type: employee-attribute-definition
              url: >-
                https://lucca.ilucca.net/lucca-api/employee-attribute-definitions/employee.givenName
              name: First Name
              multipleValueHandling: null
              taxonomy: null
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                title: employee.given-name
                maxLength: 255
                minLength: 1
                type: string
                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.
              propertyDescriptions: {}
              t9n:
                name:
                  fr-FR: Prénom
              createdAt: '2000-01-01T00:00:00+00:00'
              lastUpdatedAt: '2000-01-01T00:00:00+00:00'
              isArchived: false
              lastArchivedAt: null
          taxonomy-label: {}
  responses:
    '400':
      description: |-
        Bad request. You may:
          - (write requests) make sure the request body conforms with the expected schema.
          - double check all required parameters are set.
      headers:
        Api-Version:
          $ref: '#/components/headers/api-version'
        Deprecation:
          $ref: '#/components/headers/deprecation'
        Sunset:
          $ref: '#/components/headers/sunset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem'
          example:
            type: https://tools.ietf.org/html/rfc7231#section-6.5.1
            title: One or more validation errors occurred.
            status: 400
            instance: https://example.ilucca.net/lucca-api/leaves/1573
            errors:
              endsOn:
                - 'Invalid period: StartsOn should be before EndsOn.'
              employeeId:
                - The employeeId query parameter is required.
            extensions:
              traceId: '|78777424-49cc27e04281bbfc.'
    '401':
      description: You are not authenticated. Please refresh your token.
      headers:
        Api-Version:
          $ref: '#/components/headers/api-version'
        Deprecation:
          $ref: '#/components/headers/deprecation'
        Sunset:
          $ref: '#/components/headers/sunset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem'
          example:
            type: https://datatracker.ietf.org/doc/html/rfc7235#section-3.1
            title: Unauthorized
            status: 401
            instance: https://example.ilucca.net/lucca-api/employees/1573
    '500':
      description: Internal server error.
      headers:
        Api-Version:
          $ref: '#/components/headers/api-version'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem'
          example:
            type: https://tools.ietf.org/html/rfc7231#section-6.5.4
            title: Internal Server Error
            status: 500
            instance: https://example.ilucca.net/lucca-api/employees/1573
  securitySchemes:
    oAuth:
      type: oauth2
      description: >-
        The Lucca API implements the [oAuth 2](https://oauth.net/2/) protocol
        with the
        [client-credentials-flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).
        Refer to RFC8725.
      flows:
        clientCredentials:
          tokenUrl: https://accounts.world.luccasoftware.com/connect/token
          scopes:
            legal-entities.readonly: >-
              Read
              [legal-entities](/api-reference/latest/organization/legal-entity).
            legal-entities.readwrite: >-
              Create, update or delete
              [legal-entities](/api-reference/latest/organization/legal-entity).
            business-establishments.readonly: >-
              Read
              [business-establishments](/api-reference/latest/organization/business-establishment).
            business-establishments.readwrite: >-
              Create, update or delete
              [business-establishments](/api-reference/latest/organization/business-establishment).
            departments.readonly: Read [departments](/api-reference/latest/organization/department).
            departments.readwrite: >-
              Create, update or delete
              [departments](/api-reference/latest/organization/department).
            employees.readonly: Read [employees](/api-reference/latest/employees/employee).
            employees.readwrite: >-
              Create or update
              [employees](/api-reference/latest/employees/employee).
            employee-attribute-definitions.readonly: >-
              Read
              [employee-attribute-definitions](/api-reference/latest/employee-attributes/employee-attribute-definition).
            employee-attribute-definitions.readwrite: >-
              Create, update or delete
              [employee-attribute-definitions](/api-reference/latest/employee-attributes/employee-attribute-definition).
            employee-attributes.readonly: >-
              Read
              [employee-attributes](/api-reference/latest/employee-attributes/employee-attribute).
            employee-attributes.readwrite: >-
              Create, update or delete
              [employee-attributes](/api-reference/latest/employee-attributes/employee-attribute).
            employee-personal-records.readonly: >-
              Read
              [employee-personal-records](/api-reference/latest/employees/employee-personal-records).

              This contains highly sensitive data about the personal detail of
              the person.
            employee-personal-records.readwrite: >-
              Create, update or delete
              [employee-personal-records](/api-reference/latest/employees/employee-personal-records).

              This contains highly sensitive data about the personal detail of
              the person.
            employments.readonly: Read [employments](/api-reference/latest/employments/employment).
            employments.readwrite: >-
              Create, update or delete
              [employments](/api-reference/latest/employments/employment).
            employment-templates.readonly: >-
              Read
              [employment-templates](/api-reference/latest/employments/employment-template).
            employment-templates.readwrite: >-
              Create, update or archive
              [employment-templates](/api-reference/latest/employments/employment-template).
            job-positions.readonly: >-
              Read
              [job-positions](/api-reference/latest/employments/job-position).
            job-positions.readwrite: >-
              Create, update or delete
              [job-positions](/api-reference/latest/employments/job-position).
            probationary-periods.readonly: >-
              Read
              [probationary-periods](/api-reference/latest/employments/probationary-period).
            probationary-periods.readwrite: >-
              Create, update or delete
              [probationary-periods](/api-reference/latest/employments/probationary-period).
            occupation-categories.readonly: >-
              Read
              [occupation-categories](/api-reference/latest/employee-occupations/occupation-category).
            occupation-categories.readwrite: >-
              Create, update or delete
              [occupation-categories](/api-reference/latest/employee-occupations/occupation-category).
            job-qualifications.readonly: >-
              Read
              [job-qualifications](/api-reference/latest/employee-occupations/job-qualification)
              and
              [professions](/api-reference/latest/employee-occupations/profession).
            job-qualifications.readwrite: >-
              Create, update or delete
              [job-qualifications](/api-reference/latest/employee-occupations/job-qualification)
              and
              [professions](/api-reference/latest/employee-occupations/profession).
            taxonomies.readonly: >-
              Read [taxonomies](/api-reference/latest/taxonomies/taxonomy) and
              [taxonomy-labels](/api-reference/latest/taxonomies/taxonomy-label).
            taxonomies.readwrite: >-
              Create, update or delete
              [taxonomies](/api-reference/latest/taxonomies/taxonomy) and
              [taxonomy-labels](/api-reference/latest/taxonomies/taxonomy-label).
            webhook-endpoints.readonly: Read webhook-endpoints.
            webhook-endpoints.readwrite: Create and update webhook-endpoints.
            webhook-deliveries.readonly: Read webhook-deliveries.
            webhook-deliveries.readwrite: Send a ping event to a webhook-endpoint.
            working-time-arrangements.readonly: Read working-time-arrangements.
            files.readonly: Read files stored in Lucca.
            files.readwrite: Upload a file to Lucca.
          x-scope-metadata:
            legal-entities.readonly:
              criticality: low
              resources: '[legal-entity](./organization/legal-entity)'
            legal-entities.readwrite:
              criticality: medium
              resources: '[legal-entity](./organization/legal-entity)'
            business-establishments.readonly:
              criticality: low
              resources: '[business-establishment](./organization/business-establishment)'
            business-establishments.readwrite:
              criticality: medium
              resources: '[business-establishment](./organization/business-establishment)'
            departments.readonly:
              criticality: low
              resources: '[department](./organization/department)'
            departments.readwrite:
              criticality: medium
              resources: '[department](./organization/department)'
            employees.readonly:
              criticality: medium
              resources: '[employee](./employees/employee)'
            employees.readwrite:
              criticality: medium
              resources: '[employee](./employees/employee)'
            employee-attribute-definitions.readonly:
              criticality: low
              resources: >-
                [employee-attribute-definition](./employee-attributes/employee-attribute-definition)
            employee-attribute-definitions.readwrite:
              criticality: medium
              resources: >-
                [employee-attribute-definition](./employee-attributes/employee-attribute-definition)
            employee-attributes.readonly:
              criticality: medium
              resources: '[employee-attribute](./employee-attributes/employee-attribute)'
            employee-attributes.readwrite:
              criticality: medium
              resources: '[employee-attribute](./employee-attributes/employee-attribute)'
            employee-personal-records.readonly:
              criticality: high
              resources: '[employee-personal-record](./employees/employee-personal-record)'
            employee-personal-records.readwrite:
              criticality: high
              resources: '[employee-personal-record](./employees/employee-personal-record)'
            employments.readonly:
              criticality: medium
              resources: '[employment](./employments/employment)'
            employments.readwrite:
              criticality: medium
              resources: '[employment](./employments/employment)'
            employment-templates.readonly:
              criticality: medium
              resources: '[employment-template](./employments/employment-template)'
            employment-templates.readwrite:
              criticality: medium
              resources: '[employment-template](./employments/employment-template)'
            job-positions.readonly:
              criticality: low
              resources: '[job-position](./employments/job-position)'
            job-positions.readwrite:
              criticality: medium
              resources: '[job-position](./employments/job-position)'
            probationary-periods.readonly:
              criticality: medium
              resources: '[probationary-period](./employments/probationary-period)'
            probationary-periods.readwrite:
              criticality: medium
              resources: '[probationary-period](./employments/probationary-period)'
            occupation-categories.readonly:
              criticality: low
              resources: >-
                [occupation-category](./employee-occupation-categories/get-started)
            occupation-categories.readwrite:
              criticality: medium
              resources: >-
                [occupation-category](./employee-occupation-categories/get-started)
            job-qualifications.readonly:
              criticality: low
              resources: >-
                [job-qualification](./employee-job-qualifications/job-qualification)
                and [professions](./employee-job-qualifications/profession)
            job-qualifications.readwrite:
              criticality: medium
              resources: >-
                [job-qualification](./employee-job-qualifications/job-qualification)
                and [professions](./employee-job-qualifications/profession)
            taxonomies.readonly:
              criticality: low
              resources: >-
                [taxonomy](./taxonomies/taxonomy) &
                [taxonomy-label](./taxonomies/taxonomy-label)
            taxonomies.readwrite:
              criticality: medium
              resources: >-
                [taxonomy](./taxonomies/taxonomy) &
                [taxonomy-label](./taxonomies/taxonomy-label)
            webhook-endpoints.readonly:
              criticality: low
              resources: '[webhook-endpoint](./webhooks/webhook-endpoint)'
            webhook-endpoints.readwrite:
              criticality: medium
              resources: '[webhook-endpoint](./webhooks/webhook-endpoint)'
            webhook-deliveries.readonly:
              criticality: low
              resources: >-
                [webhook-delivery](./webhooks/webhook-delivery) &
                [webhook-delivery-attempt](./webhooks/webhook-delivery-attempt)
            webhook-deliveries.readwrite:
              criticality: medium
              resources: >-
                [webhook-delivery](./webhooks/webhook-delivery) &
                [webhook-delivery-attempt](./webhooks/webhook-delivery-attempt)
            working-time-arrangements.readonly:
              criticality: low
              resources: >-
                [working-time-arrangement](./working-time-arrangements/working-time-arrangement)
            files.readonly:
              criticality: medium
              resources: '[file](./files/file)'
            files.readwrite:
              criticality: medium
              resources: '[file](./files/file)'

````