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

# List legal-entities

> Returns a paginated list of legal-entities.

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

  ```
   legal-entities.readonly
  ```

  or

  ```
   legal-entities.readwrite
  ```
</Accordion>


## OpenAPI

````yaml /openapi-specs/lucca-api@2024-11-01.json get /lucca-api/legal-entities
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/legal-entities:
    parameters:
      - $ref: '#/components/parameters/api-version'
      - $ref: '#/components/parameters/if-none-match'
      - $ref: '#/components/parameters/if-match'
      - $ref: '#/components/parameters/accept-encoding'
      - $ref: '#/components/parameters/include'
    get:
      tags:
        - organization
      summary: List legal-entities
      description: Returns a paginated list of legal-entities.
      operationId: get-legal-entities
      parameters:
        - name: countryCode
          in: query
          description: Filter out legal-entities on the country they belong to.
          style: form
          explode: false
          schema:
            type: array
            uniqueItems: true
            maxItems: 100
            items:
              $ref: '#/components/schemas/country-code'
            examples:
              - - FRA
                - DEU
                - ESP
        - $ref: '#/components/parameters/is-archived'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      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/legal-entities.read'
              examples:
                legal-entities:
                  $ref: '#/components/examples/legal-entities.get.example'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        default:
          $ref: '#/components/responses/500'
      security:
        - oAuth:
            - legal-entities.readonly
        - oAuth:
            - legal-entities.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.
    is-archived:
      name: isArchived
      description: |-
        When omitted: return both archived and non-archived resources.
        When `true`: only return archived resources.
        When `false`: only return non-archived resources.
      in: query
      required: false
      schema:
        type: boolean
      examples:
        onlyArchived:
          value: false
    page:
      name: page
      in: query
      description: >-
        Cursor of the page to retrieve. Read more about
        [pagination](/documentation/using-api/paging).
      schema:
        type: string
      examples:
        one:
          summary: Page with token '!w.SDijk23'
          value: '!w.SDijk23'
    limit:
      name: limit
      in: query
      description: |-
        Number of items per page. Defaults to 25. Maximum is 100.
        Read more about [pagination](/documentation/using-api/paging).
      schema:
        type: integer
        default: 25
        minimum: 0
        maximum: 100
      examples:
        one:
          summary: Retrieve 25 items.
          value: 25
  schemas:
    country-code:
      title: Country Code
      description: >-
        Three letters ISO 3166-1 alpha-3 country code. Lucca uses
        [restcountries.com](https://restcountries.com/) to map these codes to
        the country names displayed in the UI.
      type: string
      format: iso-3166-alpha-3
      minLength: 3
      maxLength: 3
      enum:
        - FRA
        - ESP
        - DEU
        - CHE
        - ITA
        - GBR
        - USA
        - BEL
        - CAN
        - AFG
        - ALA
        - ALB
        - DZA
        - ASM
        - AND
        - AGO
        - AIA
        - ATA
        - ATG
        - ARG
        - ARM
        - ABW
        - AUS
        - AUT
        - AZE
        - BHS
        - BHR
        - BGD
        - BRB
        - BLR
        - BLZ
        - BEN
        - BMU
        - BTN
        - BOL
        - BIH
        - BWA
        - BVT
        - BRA
        - VGB
        - IOT
        - BRN
        - BGR
        - BFA
        - BDI
        - KHM
        - CMR
        - CPV
        - CYM
        - CAF
        - TCD
        - CHL
        - CHN
        - HKG
        - MAC
        - CXR
        - CCK
        - COL
        - COM
        - COG
        - COD
        - COK
        - CRI
        - CIV
        - HRV
        - CUB
        - CYP
        - CZE
        - DNK
        - DJI
        - DMA
        - DOM
        - ECU
        - EGY
        - SLV
        - GNQ
        - ERI
        - EST
        - ETH
        - FLK
        - FRO
        - FJI
        - FIN
        - GUF
        - PYF
        - ATF
        - GAB
        - GMB
        - GEO
        - GHA
        - GIB
        - GRC
        - GRL
        - GRD
        - GLP
        - GUM
        - GTM
        - GGY
        - GIN
        - GNB
        - GUY
        - HTI
        - HMD
        - VAT
        - HND
        - HUN
        - ISL
        - IND
        - IDN
        - IRN
        - IRQ
        - IRL
        - IMN
        - ISR
        - JAM
        - JPN
        - JEY
        - JOR
        - KAZ
        - KEN
        - KIR
        - PRK
        - KOR
        - KWT
        - KGZ
        - LAO
        - LVA
        - LBN
        - LSO
        - LBR
        - LBY
        - LIE
        - LTU
        - LUX
        - MKD
        - MDG
        - MWI
        - MYS
        - MDV
        - MLI
        - MLT
        - MHL
        - MTQ
        - MRT
        - MUS
        - MYT
        - MEX
        - FSM
        - MDA
        - MCO
        - MNG
        - MNE
        - MSR
        - MAR
        - MOZ
        - MMR
        - NAM
        - NRU
        - NPL
        - NLD
        - NCL
        - NZL
        - NIC
        - NER
        - NGA
        - NIU
        - NFK
        - MNP
        - NOR
        - OMN
        - PAK
        - PLW
        - PSE
        - PAN
        - PNG
        - PRY
        - PER
        - PHL
        - PCN
        - POL
        - PRT
        - PRI
        - QAT
        - REU
        - ROU
        - RUS
        - RWA
        - BLM
        - SHN
        - KNA
        - LCA
        - MAF
        - SXM
        - SPM
        - VCT
        - WSM
        - SMR
        - STP
        - SAU
        - SEN
        - SRB
        - SYC
        - SLE
        - SGP
        - SVK
        - SVN
        - SLB
        - SOM
        - ZAF
        - SGS
        - SSD
        - LKA
        - SDN
        - SUR
        - SJM
        - SWZ
        - SWE
        - SYR
        - TWN
        - TJK
        - TZA
        - THA
        - TLS
        - TGO
        - TKL
        - TON
        - TTO
        - TUN
        - TUR
        - TKM
        - TCA
        - TUV
        - UGA
        - UKR
        - ARE
        - UMI
        - URY
        - UZB
        - VUT
        - VEN
        - VNM
        - VIR
        - WLF
        - ESH
        - YEM
        - ZMB
        - ZWE
      examples:
        - FRA
        - DEU
    legal-entities.read:
      allOf:
        - $ref: '#/components/schemas/legal-entities'
        - $ref: '#/components/schemas/legal-entity.embedded'
    legal-entities:
      title: legal-entities
      description: Collection of legal-entity objects.
      allOf:
        - type: object
          properties:
            type:
              type: string
              const: legal-entities
            url:
              type: string
              format: uri
            totalCount:
              type:
                - integer
                - 'null'
              format: int64
              minimum: 0
              description: >-
                Total number of legal-entity resources across all pages that
                satisfy query parameters.
            items:
              type: array
              minItems: 0
              maxItems: 100
              description: Paginated list of legal-entity objects.
              items:
                $ref: '#/components/schemas/legal-entity'
        - $ref: '#/components/schemas/collection.links'
    legal-entity.embedded:
      type: object
      properties:
        embedded:
          description: >-
            No embedded resources on a legal-entity(ies) response. Expect an
            empty object if embedded are requested.
          type:
            - object
            - 'null'
    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.'
    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
          maxLength: 100
          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
          maxLength: 50
          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
    collection.links:
      type: object
      properties:
        links:
          title: Links
          description: Links to related resources
          type:
            - object
            - 'null'
          required:
            - prev
            - next
          properties:
            prev:
              allOf:
                - $ref: '#/components/schemas/link'
                - description: Link to the previous page. Is `null` on the first page.
            next:
              allOf:
                - $ref: '#/components/schemas/link'
                - description: Link to the next page. Is `null` on the last page.
    currency-code:
      title: iso-4217 currency code
      description: ISO-4217 currency code
      type: string
      format: iso-4217
      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
    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'
    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'
    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
  headers:
    api-version:
      description: Name (date of release) of the API version.
      schema:
        type: string
        const: '2024-11-01'
        examples:
          - '2024-11-01'
        maxLength: 10
      required: true
    content-encoding:
      description: >-
        HTTP representation header that lists the encodings and the order in
        which they have been applied to the representation of the resource.
      required: false
      schema:
        type: array
        uniqueItems: true
        items:
          type: string
          enum:
            - gzip
            - compress
            - deflate
            - br
      examples:
        gzip:
          value:
            - gzip
    eTag:
      description: Identifies the cached version of the resource.
      schema:
        type: string
        examples:
          - W/q5sd4w2x1c1gfdg
    deprecation:
      description: |
        Signals the resource has been deprecated.
      schema:
        type: string
        format: date
        maxLength: 10
        examples:
          - '2024-01-01'
    sunset:
      description: >
        The **Sunset** response header (see [RFC
        8594](https://datatracker.ietf.org/doc/html/rfc8594)) indicates the
        point in time at which this endpoint or resource will become
        unavailable. The sunset value is a timestamp [RFC 9110 Section
        5.6.7][rfc-9110-5.6.7] that usually points to the future. If a sunset
        value points to the past, then the endpooint or  resource must be
        expected to become unavailable at any time.

        As an API client, you should monitor the presence and value of all
        **Sunset** headers  and be ready to take counter measures.
      schema:
        type: string
        format: date-time
        examples:
          - '2026-01-01T00:00:00Z'
  examples:
    legal-entities.get.example:
      summary: legal-entities GET example
      description: legal-entities GET example
      value:
        type: legal-entities
        url: https://example.ilucca.net/lucca-api/legal-entities?limit=25
        totalCount: 121
        items:
          - 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
        embedded: {}
        links:
          prev: null
          next:
            href: >-
              https://example.ilucca.net/lucca-api/legal-entities?page=2qs1dqsd45&limit=25
  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)'

````