> ## 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.

# How to Reject Timesheets

## Introduction

There can be many reasons to reject a large set of timesheets, on top of them are mistakes in pay elements calculi.

The goal of this guide is to help you:

1. Identify timesheets that need to be rejected.
2. Reject them in order to have users submit them again.

Please, note that the action to be done depends on the actual status of the timesheets. Timesheets pending approval
will have to be **denied**, whereas approved timesheets must be **invalidated**. You can learn more about the
[approval workflow in Lucca Timesheet here](../../timmi-timesheet/timesheets/timesheet).

## Prerequisites

You will need:

* (required) Your domain name `{yourDomain}`, eg: "[https://myawesomecompany.ilucca.net](https://myawesomecompany.ilucca.net)".
* (required) An [API key](https://support.lucca.fr/hc/en-us/articles/115000084851) `{apiKey}` that has timesheet approbation and invalidation rights for the given users.

## Guide

### 1. Retrieve the timesheets to reject

You will need to get your hands on the unique identifiers `id` of the timesheets that need to be rejected. This is achieved via a filtered request on the `/api/v3/timmitimesheets` endpoint.

Most common filters for this kind of requests are:

* `?statuteId=1,2,...`: filter on a list of time regulations by their unique identifiers.
* `?status=1,2`: filter on the status of the timesheets. Here, you will most often need to retrieve timesheets with `1: PendingApproval` or `2: Approved` statuses.
* `?startsOn=since,2022-01-01`: filter on timesheets that start after the given date (here, January, 1st 2022).
* `?ownerId=1,2,...`: filter on a list of users' unique identifiers.

<Info>
  **Retrieve both statuses separately.**
  You can make your life easier by making two requests: the first to
  retrieve timesheets pending approval, and a second one to retrieve
  approved timesheets.
</Info>

<Warning>
  **Please page your request.**
  Requests aimed at retrieving a large set of resources should be
  paged. [You can read more about paging here](../../introduction).
</Warning>

Request should look like this (here both statuses are retrieved at the same time `?status=1,2` for simplicity sake):

```http theme={null}
GET /api/v3/timmitimesheets?statuteId=1,2&status=1,2&startsOn=since,2022-01-01&paging=0,1000&fields=id,status,ownerId,startsOn,statuteId,collection.count HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Response:
{
  "data": {
    count: 2,
    "items": [
      {
        "id": 123,
        "status": 1,
        "ownerId": 416,
        "startsOn": "2022-01-01",
        "statuteId": 1
      },
      {
        "id": 124,
        "status": 2,
        "ownerId": 416,
        "startsOn": "2022-02-01",
        "statuteId": 1
      }
    ]
  }
}
```

### 2. Deny timesheets pending approval

First, isolate timesheets that are pending approval (ie `status == 1`).

And forge the following request ([see API reference](../workflow/deny-timesheet)):

```http theme={null}
POST /timmi/services/workflow/deny HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Content-Type: application/json

{
  "timesheets": [
    {
      "id": 123,
      "comment": "Mass invalidation"
    },
    ...
  ]
}
```

Please use the "comment" to explain the cause of this rejection. It will be shown to the user on the timesheet.

The users will be sent an email notifying them of their timesheet(s) rejection.

### 3. Invalidate approved timesheets

Then, isolate timesheets that are pending approval (ie `status == 2`).

And forge the following request ([see API reference](../workflow/invalidate-timesheet)):

```http theme={null}
POST /timmi/services/workflow/invalidate HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Content-Type: application/json

{
  "timesheets": [
    {
      "id": 124,
      "comment": "Mass invalidation"
    },
    ...
  ]
}
```

Please use the "comment" to explain the cause of this rejection. It will be shown to the user on the timesheet.

The users will be sent an email notifying them of their timesheet(s) rejection.