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

# List Users

> Retrieve a list of Users.

By default, former employees are excluded from the response. In order to retrieve them, you may add the `?dtContractEnd=notequal,null` query parameter to your request.


<Warning>
  This legacy endpoint has its equivalent in the **Lucca API** (currently in beta): [`GET /lucca-api/employees`](/api-reference/latest/get-employees).

  To retrieve all employee data (including extensions) in a single call, you may also use [`GET /lucca-api/employee-attributes`](/api-reference/latest/get-employee-attributes), filterable by employee.
</Warning>


## OpenAPI

````yaml /openapi-specs/directory-v3.yaml get /api/v3/users
openapi: 3.1.0
info:
  title: Directory-v3
  version: '1.0'
  description: |
    Welcome on the documentation for the Directory v3 API.
  contact:
    name: API Support
    url: https://support.lucca.fr
    email: contact@luccasoftware.com
  license:
    name: Unlicensed
    url: https://www.luccasoftware.com
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: Users
    description: Users or employees.
  - name: Work-Contracts
    description: Work-contracts.
paths:
  /api/v3/users:
    parameters:
      - $ref: '#/components/parameters/Authorization'
    get:
      tags:
        - Users
      summary: List Users
      description: >
        Retrieve a list of Users.


        By default, former employees are excluded from the response. In order to
        retrieve them, you may add the `?dtContractEnd=notequal,null` query
        parameter to your request.
      operationId: get-api-v3-users
      parameters:
        - name: id
          in: query
          description: User's identifier.
          style: form
          explode: false
          schema:
            type: array
            uniqueItems: true
            items:
              type: integer
              minimum: 1
        - name: dtContractStart
          in: query
          description: |
            Format: `({comparator},)?{date}`.
          schema:
            type: string
        - name: dtContractEnd
          in: query
          description: |
            Format: `({comparator},)?{date | 'null'}`.
          schema:
            type:
              - string
              - 'null'
            examples:
              - '2025-01-01'
              - since,2025-01-01
              - until,2025-01-31
              - between,2025-01-01,2025-01-31
              - 'null'
              - notequal,null
        - name: modifiedAt
          in: query
          description: |-
            Only return users/employees who have been modified since {date}.

            Format: '{comparator},{date-time}'
          schema:
            type: string
            example: since,2025-01-01T08:45:23
        - $ref: '#/components/parameters/paging'
        - $ref: '#/components/parameters/usersFields'
        - name: mail
          in: query
          description: >-
            User's mail (strict equality). You may prefix with the `like,`
            operator in order to execute a LIKE search (e.g.:
            `?mail=like,jdoe`).
          schema:
            type: string
        - name: login
          in: query
          description: User's login (strict equality).
          schema:
            type: string
        - name: formerEmployees
          description: >-
            Whether former (terminated) employees should be included in response
            `?formerEmployees=true` along active employees. **They are excluded
            by default**. Please note that you may not be able to retrieve
            former employees even when including them, depending on your access
            rights.
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          allOf:
                            - $ref: '#/components/schemas/User'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: User Not Found
components:
  parameters:
    Authorization:
      name: Authorization
      required: true
      description: 'API key. Value must be formatted like so: `lucca application={api_key}`.'
      in: header
      schema:
        type: string
    paging:
      name: paging
      in: query
      description: |-
        Format: `{offset},{limit}`, where:
        - `offset`: index of the first item to retrieve in the collection.
        - `limit`: maximum number of items to retrieve.

        Maximum limit is "1000".'
      schema:
        type: string
        default: 0,1000
    usersFields:
      name: fields
      in: query
      description: >
        Comma-separated list of fields of the user to include in responses.
        Extended data can be retrieved with `?fields=extendedData`.
      schema:
        type: string
      example: id,firstName,lastName,dtContractStart,legalEntity[id,name]
  schemas:
    User:
      title: User (v3)
      allOf:
        - $ref: '#/components/schemas/BaseUser'
        - type: object
          properties:
            applicationData:
              allOf:
                - $ref: '#/components/schemas/application-data'
                - readOnly: true
            extendedData:
              allOf:
                - $ref: '#/components/schemas/extended-data'
                - readOnly: true
      example:
        id: 416
        name: John Doe
        url: http://example.ilucca.net/api/users/1
        displayName: Doe John
        modifiedAt: '2015-09-07T10:20:06.583'
        lastName: DOE
        firstName: John
        login: jdoe
        mail: no-reply@lucca.fr
        dtContractStart: '2014-09-01T00:00:00'
        dtContractEnd: null
        birthDate: '1989-12-22T00:00:00'
        employeeNumber: '00057'
        calendarId: 1
        calendar:
          id: 1
          url: http://example.ilucca.net/api/v3/publicHolidayCalendars/1
          name: Jours fériés en France
        cultureID: 1036
        culture:
          id: 1036
          name: français (France)
          url: http://example.ilucca.net/api/v3/cultures/1036
        picture:
          id: 74d381db-dd4d-4f64-bc1e-582d806e58a8
          url: >-
            http://example.ilucca.net/api/v3/files/74d381db-dd4d-4f64-bc1e-582d806e58a8
          name: jdoe.png
        legalEntityId: 1
        legalEntity:
          id: 1
          name: Lucca
          url: http://example.ilucca.net/api/v3/legalEntities/1
        departmentId: 13
        department:
          id: 13
          name: BU Timmi/Lucca
          url: http://example.ilucca.net/api/v3/departments/13
        managerId: 383
        manager:
          id: 383
          name: Roger Smith
          url: http://example.ilucca.net/api/v3/users/383
        rolePrincipalId: 55
        rolePrincipal:
          id: 55
          name: User
          url: http://example.ilucca.net/api/v3/roles/55
        habilitedRoles:
          - id: 59
            name: Employee +
            url: http://example.ilucca.net/api/v3/roles/59
          - id: 63
            name: Analytics access
            url: http://example.ilucca.net/api/roles/63
        userWorkCycles:
          - id: 288
            ownerID: 416
            workCycleID: 6
            startsOn: '1900-01-01T00:00:00'
            endsOn: '2015-03-09T00:00:00'
          - id: 289
            ownerID: 416
            workCycleID: 9
            startsOn: '2015-03-10T00:00:00'
            endsOn: '2015-10-13T00:00:00'
          - id: 317
            ownerID: 416
            workCycleID: 14
            startsOn: '2015-10-13T00:00:00'
            endsOn: '9999-12-31T00:00:00'
        allowsElectronicPayslip: true
        userAxisValues_2:
          id: 35
    BaseUser:
      type: object
      required:
        - firstName
        - lastName
        - login
        - mail
        - dtContractStart
        - legalEntityId
        - employeeNumber
        - departmentId
        - managerId
        - rolePrincipalId
        - habilitedRoles
        - birthDate
        - calendarId
        - cultureID
      properties:
        id:
          type: number
          minimum: 1
          readOnly: true
          description: Unique identifier
        url:
          type: string
          format: uri
          minLength: 1
          readOnly: true
        firstName:
          type: string
          minLength: 1
          description: Employee's first name (given name).
        lastName:
          type: string
          minLength: 1
          description: Employee's last name (family name).
        name:
          type: string
          minLength: 1
          readOnly: true
          description: Concatenation of both the firstName and lastName
        displayName:
          type: string
          minLength: 1
          readOnly: true
          description: Concatenation of both the lastName and firstName.
        login:
          type: string
          minLength: 1
          description: '**Unique** identifier of this employee.'
        mail:
          type: string
          minLength: 1
          description: Employee's professional email address.
        dtContractStart:
          type: string
          format: date-time
          description: First day of employment.
        dtContractEnd:
          type:
            - string
            - 'null'
          format: date-time
          description: Last day of employment. Leave `null` if unknown.
        legalEntityId:
          type: integer
          minimum: 1
          description: Establishment this employee works for.
        legalEntity:
          type: object
          description: >-
            Embedded representation of the establishment this employee works
            for.
          readOnly: true
          properties:
            id:
              type: integer
              minimum: 1
              readOnly: true
            name:
              type: string
              readOnly: true
            url:
              type: string
              format: uri
              readOnly: true
        employeeNumber:
          type:
            - string
            - 'null'
          minLength: 1
          description: Employee number. Must be unique by establishment (i.e. legalEntity).
        departmentId:
          type: integer
          minimum: 1
          description: Identifier of the department this employee works in.
        department:
          type: object
          readOnly: true
          description: >-
            Embedded representation of the department. Read more about
            [departments](/api-reference/legacy/organization/departments/department).
          properties:
            id:
              type: integer
              minimum: 1
              description: Identifier of the department this user/employee works in.
              readOnly: true
            name:
              type: string
              minLength: 1
              description: Name of the department this user/employee works in.
              readOnly: true
            url:
              type: string
              format: uri
              description: URL of the department resource.
              readOnly: true
        managerId:
          type:
            - integer
            - 'null'
          description: >-
            Identifier this user/employee's manager. Is also a user/employee.
            `Null` may be interpreted as "this employee has no manager but
            themselves".
        manager:
          type: object
          properties:
            id:
              type: integer
              minimum: 1
              readOnly: true
              description: >-
                Identifier this user/employee's manager. Is also a
                user/employee.
            firstName:
              type: string
              minLength: 1
              description: The manager's first name.
            lastName:
              type: string
              minLength: 1
              description: The manager's last name.
            url:
              type: string
              format: uri
        cspId:
          type:
            - integer
            - 'null'
          minimum: 1
          description: Identifier of the socio-professional category of this employee.
        nationalityId:
          type:
            - string
            - 'null'
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2 country code
          examples:
            - FR
            - UK
            - US
            - ES
            - IT
            - DE
        seniorityDate:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Seniority date of this employee. If left `null`, you may fall back
            on this employee's `dtContractStart`.
        birthDate:
          type:
            - string
            - 'null'
          format: date-time
          description: Birth date of this employee.
        insuranceNumber:
          type:
            - string
            - 'null'
          description: Social security number of this employee.
        cultureID:
          type: integer
          minimum: 1025
          maximum: 58380
          description: Language code identifiers (LCID).
          examples:
            - 1036
            - 1033
            - 1031
            - 1034
        calendarId:
          type:
            - integer
            - 'null'
          minimum: 1
          description: Unique identifier of this employee's business-holidays calendar.
        calendar:
          type: object
          required:
            - id
          properties:
            id:
              type: integer
              minimum: 1
              description: >-
                Unique identifier of the business-holidays calendar that applies
                to this user/employee.
            url:
              type: string
              minLength: 1
              readOnly: true
            name:
              type: string
              minLength: 1
              readOnly: true
        userWorkCycles:
          type: array
          description: >-
            Work-cycles describe the expected (recurring) working hours of the
            employee. An employee may be given multiple work-cycles over their
            career, but no two may overlap.
          items:
            required:
              - workCycleID
              - startsOn
              - endsOn
            properties:
              id:
                type: integer
                readOnly: true
              ownerID:
                type: integer
                description: Identifier of the employee.
                readOnly: true
              workCycleID:
                type: integer
                minimum: 1
                description: Identifier of the workcycle.
              startsOn:
                type: string
                format: date-time
              endsOn:
                type:
                  - string
                  - 'null'
                format: date-time
              workCycle:
                type: object
                readOnly: true
                properties:
                  id:
                    type: integer
                    minimum: 1
                    readOnly: true
                  name:
                    type: string
                    readOnly: true
                  url:
                    type: string
                    format: uri
                    readOnly: true
        picture:
          type: object
          description: Profile picture of this user/employee.
          required:
            - id
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier of the user/employee's picture file.
            href:
              type: string
              format: uri
              readOnly: true
              description: Follow this link in order to retrieve the image file.
        rolePrincipalId:
          type: integer
          minimum: 1
          description: >-
            Identifier of the "primary" role this user/employee has.


            There are two types of roles: "primary" and "secondary". A
            user/employee must have a single primary role, that dictates their
            overall level of access, as well as zero or several complementary
            "secondary" roles.
        rolePrincipal:
          type: object
          required:
            - id
          properties:
            id:
              type: number
              readOnly: true
              description: Identifier of the "primary" role this user/employee has.
            name:
              type: string
              minLength: 1
              readOnly: true
              description: Name of the "primary" role this user/employee has.
            url:
              type: string
              minLength: 1
              readOnly: true
        habilitedRoles:
          description: >-
            List of "secondary" (complementary) roles given to this
            user/employee.
          type: array
          uniqueItems: true
          items:
            required:
              - id
            properties:
              id:
                type: integer
                minimum: 1
              name:
                type: string
                minLength: 1
                readOnly: true
              url:
                type: string
                minLength: 1
                readOnly: true
        address:
          type:
            - string
            - 'null'
          description: Personal address of this user/employee.
        directLine:
          type:
            - string
            - 'null'
          format: phone
          description: Professional landline phone number of this user/employee.
        jobTitle:
          type:
            - string
            - 'null'
          minLength: 1
          description: Job title of this user/employee.
        gender:
          description: Employee declared gender.
          type: string
          enum:
            - Undefined
            - Male
            - Female
            - Misc
          default: Undefined
        personalEmail:
          type:
            - string
            - 'null'
          format: email
          description: Personal email address of this user/employee.
        personalMobile:
          type:
            - string
            - 'null'
          format: phone
          description: Personal mobile phone number of this user/employee.
        professionalMobile:
          type:
            - string
            - 'null'
          format: phone
          description: Professional mobile phone number of this user/employee.
        allowsElectronicPayslip:
          type:
            - boolean
            - 'null'
          description: >-
            Whether this user/employee gave their consent to receive their
            payslip in an electronic format (i.e. PDF and email) rather than
            through physical means. This property is used by the Lucca Payslips
            application.
        quote:
          type:
            - string
            - 'null'
          description: >-
            Optional personal quote of this user/employee. Reflects their mood
            and/or character. Displayed in the "who's who".
        personalCard:
          type:
            - string
            - 'null'
          description: Personal credit card number. Only when Lucca Expenses is installed.
        corporateCard:
          type:
            - string
            - 'null'
          description: Coporate credit card number. Only when Lucca Expenses is installed.
        bankName:
          type:
            - string
            - 'null'
          description: Name of bank of this user/employee bank account.
        rib:
          description: >-
            Employee personal bank account RIB (French: "Relevé d'identité
            Bancaire").
          type:
            - string
            - 'null'
        iban:
          description: >-
            Employee personal bank account IBAN (International Bank Account
            Number).
          type:
            - string
            - 'null'
        bic:
          description: Employee personal bank account SWIFT BIC code (routing number).
          type:
            - string
            - 'null'
        frenchCarTaxHorsePower:
          type:
            - integer
            - 'null'
          description: >-
            Number of fiscal horspowers of the employee car in the context of
            mileage-related expense claims. Only when Lucca Expenses is
            installed.
        frenchMotocyclesTaxHorsePower:
          type:
            - integer
            - 'null'
          description: >-
            Number of fiscal horspowers of the employee motorcycle in the
            context of mileage-related expense claims. Only when Lucca Expenses
            is installed.
        unitSellPrice:
          type:
            - number
            - 'null'
          format: double
          description: Legacy property. Should not be used.
        modifiedAt:
          type: string
          format: date-time
          description: >-
            Timestamp of the last time this user/employees attributes were
            modified.
          minLength: 1
      additionalProperties: true
    application-data:
      type: object
      properties:
        profile_figgo:
          description: Leave accrual profile in Lucca Absences
          type:
            - object
            - 'null'
          properties:
            id:
              type: integer
              minimum: 1
            name:
              type: string
              readOnly: true
            url:
              type: string
              format: url
              readOnly: true
        fullTimeEquivalent:
          description: Full-time equivalent ratio in Lucca Compensation.
          type:
            - object
            - 'null'
          properties:
            value:
              type: string
            link:
              type:
                - object
                - 'null'
        theoreticalRemuneration:
          description: Theoretical compensation in Lucca Compensation.
          type:
            - object
            - 'null'
          properties:
            value:
              type: string
            link:
              type:
                - object
                - 'null'
              properties:
                url:
                  type: string
                  format: url
                text:
                  type: string
                  minLength: 1
        manager2Id:
          description: >-
            Manager 2 may be used in the Lucca Absences approval workflow
            (depends on how it is configured).


            `manager2Id` should be used in write requests, and `manager2` in
            read requests in order to retrieve the corresponding user
            representation.
          type:
            - integer
            - 'null'
        manager2:
          type:
            - object
            - 'null'
          readOnly: true
          properties:
            id:
              type: integer
              minimum: 0
              readOnly: true
            name:
              type: string
              minLength: 1
              readOnly: true
            url:
              type: string
              format: uri
              readOnly: true
      additionalProperties: true
      example:
        profile_figgo:
          id: 1
          name: Cadre (218 jours)
          url: https://example.ilucca.net/api/v3/leaveprofiles/1
        profile_cleemy_89:
          id: 23
          name: Regular employee
          url: https://example.ilucca.net/api/v3/expenseprofiles-89/23
        fullTimeEquivalent:
          value: Full time
          link: null
        theoreticalRemuneration:
          value: 87,000.00 €
          link:
            url: https://example.ilucca.net/popleerem/remunerations#/416
            text: Go to Lucca Compensation
        manager2: null
    extended-data:
      type: object
      description: >-
        Dictionary of extended data, which are custom extensions to the base
        user/employee model. Keys are the custom extended-data definition
        identifier (e.g. `e_Emergency-Contact`). The value is polymorphic, and
        its type depends on the extended-data definition.


        Read more about [extended
        data](/api-reference/legacy/directory/guides/extended-data).
      additionalProperties: true

````