> ## 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 Submit Timesheets

## Introduction

### You Goal

There can be many reasons to submit timesheets through API requests. A common use case is to submit timesheets
[that were already automatically filled with TimeEntries through previous API requests](./update-time-entries).
If there is no need to let the employee adjust it, then you can submit their timesheet for them directly.

### What Is a Timesheet?

> Timesheets are TimeEntries containers. A timesheet belongs to a single user `owner` and ranges over several days `[startsOn - endsOn[`
> (endsOn excluded). Its range depends on the submission frequency set up in Lucca Timesheet (weekly / monthly).
>
> A timesheet purpose is to ease the approval workflow: rather than approving each TimeEntry individually, they are approved in a weekly / monthly batch.

[See the Timesheet API Reference for additional information on timesheets and approval workflow.](../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 submission rights for the given users.

## Guide

### 1. Identify Timesheets Due For Submission

You first need to get your hands on the unique identifiers `ownerId` of the timesheet owners you will want to submit timesheets.

Then, you can list all due timesheets with a GET request to `/api/v3/timmitimesheets/remindable`,
filtering either on `ownerIds`, `managerIds` or `legalEntityIds`.
[See the API reference here.](../timesheets/list-due-timesheets)

While a timesheet is only created upon submitting it, you can still retrieve "calculated" timesheets
that represent the ones that still have not been submitted. These timesheets all have an `id` equal to 0 (zero).

```http theme={null}
POST /api/v3/timmitimesheets/remindable?ownerids=45,16&fields=id,startsAt,endsAt,status,ownerid HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Content-Type: application/json

{
  "items": [
    {
      "id": 0,
      "startsAt": "2024-01-29T00:00:00",
      "endsAt": "2024-02-26T00:00:00",
      "status": 0,
      "ownerId": 16
    },
    {
      "id": 0,
      "startsAt": "2024-02-26T00:00:00",
      "endsAt": "2024-04-01T00:00:00",
      "status": 0,
      "ownerId": 16
    },
    {
      "id": 0,
      "startsAt": "2024-04-29T00:00:00",
      "endsAt": "2024-05-06T00:00:00",
      "status": 0,
      "ownerId": 45
    },
    {
      "id": 0,
      "startsAt": "2024-04-01T00:00:00",
      "endsAt": "2024-04-29T00:00:00",
      "status": 0,
      "ownerId": 16
    },
    {
      "id": 0,
      "startsAt": "2024-04-29T00:00:00",
      "endsAt": "2024-05-27T00:00:00",
      "status": 0,
      "ownerId": 16
    },
    ...
  ]
}
```

### 2. Submit Timesheets

Timesheets must be submitted in chronological order (from the oldest to the newest). On any request submitting a
given N timesheet, if there is an older N-1, N-2, ... timesheet pending submission for that user, the request will return an error.

Hence, you can either :

1. Submit timesheets for each user precisely in chronological order from the oldest to the latest.
2. Include all timesheets pending submission in a single request (easiest solution)

> `Transfer` authorizations can be set up at Timesheets' regulation level to link 2 Timesheet accounts, allowing upon timesheet submission and following approval workflow steps to transfer a certain duration amount from the to-be-debited account to the to-be-credited account.
>
> [See Timesheet API reference](../timesheets/timesheet) and [Transfer API reference](../workflow/transfer) for additional information.

Continuing the example above, if you want to submit John (id=16) first 2 timesheets with a transfer for the first one, and Sarah (id=45) early may timesheet, the easiest solution is to send the following request :

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

{
  "timesheets": [
    {
      "startsAt": "2024-01-29T00:00:00",
      "endsAt": "2024-02-26T00:00:00",
      "ownerId": 16,
      "transfers": [
        {
          "transferAuthorizationId": 0,
          "amount": "02:00:00",
          "comment": "2h extra hours to be paid. Discussed with Tom."
        }
      ]
    },
    {
      "startsAt": "2024-02-26T00:00:00",
      "endsAt": "2024-04-01T00:00:00",
      "ownerId": 16,
    },
    {
      "startsAt": "2024-04-29T00:00:00",
      "endsAt": "2024-05-06T00:00:00",
      "ownerId": 45,
    }
  ]
}
```

As a result, the following timesheets would have been submitted:

```http theme={null}
{
  "id": 10539,
  "startsAt": "2024-01-29T00:00:00",
  "endsAt": "2024-02-26T00:00:00",
  "status": 1,
  "ownerId": 16
},
{
  "id": 10540,
  "startsAt": "2024-02-26T00:00:00",
  "endsAt": "2024-04-01T00:00:00",
  "status": 1,
  "ownerId": 16
},
{
  "id": 10542,
  "startsAt": "2024-04-01T00:00:00",
  "endsAt": "2024-04-29T00:00:00",
  "status": 1,
  "ownerId": 45
}
```

But those later timesheets would still be pending submission:

```http theme={null}
{
  "id": 0,
  "startsAt": "2024-04-01T00:00:00",
  "endsAt": "2024-04-29T00:00:00",
  "status": 0,
  "ownerId": 16
},
{
  "id": 0,
  "startsAt": "2024-04-29T00:00:00",
  "endsAt": "2024-05-27T00:00:00",
  "status": 0,
  "ownerId": 16
}
```