> ## 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 leaves > Retrieve a list of approved leaves for one or several users on a given period. You MUST filter out results both on a date-range as well as a set of employees through the following query parameters. In regards to employees filtering, you may: - either retrieve Leaves of a set of specific **employees**: `?leavePeriod.ownerId=5,6,7` - or retrieve Leaves of employees working in a set of specific **departments**: `?leavePeriod.owner.departmentId=3,4,5` - or retrieve Leaves of employees working in a set of specific **establishments**: `?leavePeriod.owner.legalEntityId=1,2,3` The `date` query parameter can operate comparisons with a given date value: - `?date=2021-01-01`: strict equality. - `?date=since,2021-01-01`: greater than or equal. - `?date=until,2021-01-01`: lower than or equal. - `?date=between,2021-01-01,2021-01-31`: comprised between two dates. ## OpenAPI ````yaml /openapi-specs/timmi-absences-v3.yaml get /api/v3/leaves openapi: 3.1.0 info: title: Lucca Absences API version: '1.0' description: Welcome on the documentation for Lucca Absences 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: Leaves description: Absences taken on a given day - name: Leave Requests description: Workflow object for submiting an absence. - name: Imports description: Absences imports - name: SickLeaveCertificates description: >- Complementary data for certain leave types in order to comply with French law. paths: /api/v3/leaves: parameters: - $ref: '#/components/parameters/Authorization' get: tags: - Leaves summary: List leaves description: >- Retrieve a list of approved leaves for one or several users on a given period. You MUST filter out results both on a date-range as well as a set of employees through the following query parameters. In regards to employees filtering, you may: - either retrieve Leaves of a set of specific **employees**: `?leavePeriod.ownerId=5,6,7` - or retrieve Leaves of employees working in a set of specific **departments**: `?leavePeriod.owner.departmentId=3,4,5` - or retrieve Leaves of employees working in a set of specific **establishments**: `?leavePeriod.owner.legalEntityId=1,2,3` The `date` query parameter can operate comparisons with a given date value: - `?date=2021-01-01`: strict equality. - `?date=since,2021-01-01`: greater than or equal. - `?date=until,2021-01-01`: lower than or equal. - `?date=between,2021-01-01,2021-01-31`: comprised between two dates. operationId: get-leaves parameters: - $ref: '#/components/parameters/paging' - name: leaveAccountId in: query description: ID of the leave-account the leave must have been taken on. style: form explode: false schema: type: array items: type: integer minimum: 1 - name: date in: query required: true description: '{comparator},{date-time}' schema: type: string examples: - '2021-01-01' - since,2021-01-01 - until,2021-01-01 - between,2021-01-01,2021-01-31 - name: leavePeriod.ownerId in: query description: Employee's identifier style: form explode: false schema: type: array items: type: integer minimum: 1 - name: leavePeriod.owner.departmentId in: query description: Employees department identifier style: form explode: false schema: type: array items: type: integer minimum: 1 - name: leavePeriod.owner.legalEntityId in: query description: Employees establishment (i.e. legal-entity) identifier style: form explode: false schema: type: array items: type: integer minimum: 1 responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/Leave' '400': description: Bad Request '401': description: Unauthorized '404': description: Not Found '500': description: Internal Server Error 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 required: true schema: type: string example: 2000,500 description: '{offset},{limit}. Defaults to 0,1000.' schemas: Leave: title: The Leave resource type: object examples: [] x-tags: - Leaves properties: id: type: string description: Unique identifier for the Leave date: type: string format: date description: Date of the leave in ISO format `yyyy-mm-dd` isAm: type: boolean description: Has the value `true` for morning or the value `false` for afternoon leaveAccountId: type: integer description: Unique identifier for the attached LeaveAccount leaveAccount: $ref: '#/components/schemas/LeaveAccount' leavePeriodId: type: integer description: Unique identifier for the attached LeavePeriod leavePeriod: $ref: '#/components/schemas/LeavePeriod' value: type: - string - 'null' format: duration description: Leave duration in hours creationDate: type: string format: date-time description: Time at which the object was created isActive: type: boolean description: > Has the value `true` when the Leave exists (for pending or confirmed LeavePeriods), or the value `false` when it has been deleted (for canceled or denied LeaveRequests). cancellationDate: type: - 'null' - string format: date-time description: Time at which the request was canceled cancellationUserId: type: - 'null' - integer default: null description: 'Unique identifier for the user who canceled the request ' comment: type: string description: Comments required: - id - date - isAm - leaveAccountId - leavePeriodId LeaveAccount: title: The LeaveAccount resource x-tags: - Leaves type: object description: >- **LeaveAccounts** are the type of absences that can be selected by the user ## Fields examples: [] properties: id: type: integer description: Unique identifier for the LeaveAccount name: type: string description: Name of the LeaveAccount LeavePeriod: title: The LeavePeriod resource type: object examples: [] x-tags: - Leave Requests properties: id: type: number description: Unique identifier for the LeavePeriod ownerId: type: number description: 'Unique identifier for the user ' isConfirmed: type: boolean description: >- Has the value `true` for approved LeavePeriod or the value `false` for LeavePeriod pending approval confirmationDate: type: - 'null' - string format: date-time description: Time at which the LeavePeriod was approved attachmentId: type: - 'null' - string description: Unique identifier for the attached document leaves: type: array items: type: object description: Leave objects logs: type: array items: $ref: '#/components/schemas/LeavePeriodLog' LeavePeriodLog: title: The LeavePeriodLog resource type: object description: '## Fields' properties: id: type: integer date: type: string format: date-time comment: type: string status: type: number enum: - 0 - 2 - 3 - 4 - 5 description: | - 0 = PENDING_APPROVAL - 2 = APPROVED - 3 = DENIED - 4 = CANCELLED - 5 = CANCELLATION_PENDING ````