> ## 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 multiple time-entries > List all time-entries satisfying query filters. For technical purposes, a time-entry of duration 00:00:00 will be returned for any day if : - The day belongs to a Timesheet that is at least submitted, - And the day has 00:00:00 total working time (a public holiday, a full-day absence, a working day without any work) Read more about the [time-entry object](/api-reference/legacy/timmi-timesheet/time-entries/time-entry). Please see [this guide](/api-reference/legacy/timmi-timesheet/guides/retrieve-time-entries) on how to retrieve `time-entries` the right way. ## OpenAPI ````yaml /openapi-specs/timmi-timesheet-v3.yaml get /api/v3/timeentries openapi: 3.1.0 info: title: Lucca Timesheet API version: '1.0' description: | Welcome on the documentation for the Lucca Timesheet 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: TimeEntries description: time-entries are the actual working hours observed by a user. - name: Timesheets description: Collection of time-entries for a User over a week / month. - name: Activities description: Time-entries referencing axis-sections to describe what the user has done. - name: Attendance description: Time-entries indicating working hours. - name: Workflow description: All actions regarding the approval process of timesheets. - name: Reports description: Reporting features of Lucca Timesheet. paths: /api/v3/timeentries: parameters: - $ref: '#/components/parameters/Authorization' get: tags: - TimeEntries summary: List multiple time-entries description: >- List all time-entries satisfying query filters. For technical purposes, a time-entry of duration 00:00:00 will be returned for any day if : - The day belongs to a Timesheet that is at least submitted, - And the day has 00:00:00 total working time (a public holiday, a full-day absence, a working day without any work) Read more about the [time-entry object](/api-reference/legacy/timmi-timesheet/time-entries/time-entry). Please see [this guide](/api-reference/legacy/timmi-timesheet/guides/retrieve-time-entries) on how to retrieve `time-entries` the right way. operationId: get-api-v3-timeentries parameters: - $ref: '#/components/parameters/paging' - schema: type: array items: type: integer in: query name: ownerId description: Filter out time-entries on its ownerIds style: form explode: false - schema: type: string example: between,2021-01-01,2021-02-01 in: query name: startsAt description: '{comparator},{date-time}. Filter out time-entries on its startsAt.' - schema: type: string in: query name: axisSections.id description: Filter on a comma-separated list of AxisSections identifiers. style: form - schema: type: array items: type: string in: query name: axisSections.code description: Filter on a comma-separated list of AxisSections codes. style: form - schema: type: string example: since,2021-01-01T08:45:23Z in: query name: modifiedAt description: >- {comparator},{date-time}. Filter out time-entries on their modifiedAt. - schema: type: string example: since,2021-01-01T08:45:23Z in: query name: archivedAt description: '{comparator},{date-time}. Filter out time-entries on their startsAt.' - schema: type: string in: query name: orderBy description: '{fieldName},{direction}. Defaults to {id},{asc}' responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: count: type: integer items: type: array items: $ref: '#/components/schemas/TimeEntry' '400': $ref: '#/components/responses/ResponseProblem' '401': $ref: '#/components/responses/ResponseProblem' '404': $ref: '#/components/responses/ResponseProblem' '500': $ref: '#/components/responses/ResponseProblem' 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: TimeEntry: title: The time-entry resource type: object description: >- time-entries are the working time sequences spent by a user on any given day. time-entries come in different **units** and **submission modes** that should match the timesheet configuration of a given owner on a given day. ## About units & duration Lucca Timesheet supports up to 3 different units when it comes to entering time-entries. These are: - `0: Days` In this case, the user does not enter the exact hours he/she started working, but rather the total duration spent as a fraction of a day. For example: "John worked half a day on Monday". - `1: Hours` In this case, the user still does not enter the exact hours, but only the duration spent in hours. For example: "John worked 7h30min yesterday". - `2: Time` In this unit, the user has to enter the actual time he/she started working, as well as the end time. For example: "John started working at 08:00 for 3 hours, thus ending at 11:00". ```csharp enum TimeEntryUnit: { Days = 0, Hours = 1, Time = 2 } ``` Whichever the unit, the time-entry is mainly determined by three properties: - `(int) ownerId`: The user it belongs to. - `(date-time) startsAt`: The date and time when the user started working. In `Days` and `Hours` units, the time part can only be `00:00:00` for "morning" (AM) or `12:00:00` for the "afternoon" (PM). - `(duration) duration`: The total time spent by the user from the time he/she started. In all units, this property is serialized as a string compliant with the Timespan formating: `d.hh:mm:ss` where `d` is the number of days (can be omitted if equal to zero which is in most cases), `hh` the number of hours, `mm` the number of minutes, and `ss` the number of seconds. Some examples : ```js // TIME UNIT // Case: "John (id: 416) worked between 09:45 and 12:15 on January, 1st 2021." var timeEntry = { "ownerId": 416, "startsAt": "2021-01-01 09:45:00", "duration: "02:30:00", "unit": 2 }; // HOURS UNIT // Case: "John (id: 416) spent 4h45min working on January, 1st 2021 in the morning" var timeEntry = { "ownerId": 416, "startsAt": "2021-01-01 00:00:00", "duration: "04:45:00", "unit": 1 } // DAYS UNIT // Case: "John (id: 416) worked on the afternoon of January, 1st 2021" var timeEntry = { "ownerId": 416, "startsAt": "2021-01-01 12:00:00", "duration: "12:00:00", "unit": 0 } ``` ## About submission modes There are 2 submission modes in Lucca Timesheet: - **Attendance**: the user is expected to enter the sequences of work without much detail. - **Activities**: the user is expected to enter the time spent on each task / project / whatever. Therefore, time-entries in activities mode have a supplementary property: the set of task / project / cost center / ... the user worked on. These analytical items are called AxisSections. [More info here](reference/Timmi-Timesheet-v3.yaml/components/schemas/AxisSection). The time-entry is NOT determined by the `axisSection[]` it is associated with as a user can change the `axisSection[]`. ```json { "ownerId": 416, "startsAt": "2021-01-01 00:00:00", "duration: "04:45:00", "unit": 1, "axisSections": [ { "name": "R&D", "axis": { "name": "Cost centers" } }, { "name": "My awesome project", "axis": { "name": "Projects" } }, { "name": "Testing", "axis": { "name": "Tasks" } } ] } ``` ## About time types Each time-entry can reference a time type via its `timeTypeId` property. Time types are a configured working time classification. It is generally used as a way of discriminating different types of working hours regarding compensation: - Attendance - Travels - etc... Time types can only be used on users that belong to a specific regulation (ie time and attendance policy) mode: `timeTrackingMode: typed`. Whenever it is not the case, the `timeTypeId` property should be left `null`. ## Validation rules #### Locked timeentries after timesheet submission A time-entry cannot be modified if its `startsAt` date belongs to an already submitted or approved timesheet. #### StartsAt and timezones The `startsAt` date-time property must be considered a [floating](https://www.w3.org/International/wiki/FloatingTime) date-time. As such, no UTC offset should be sent when creating or editing a time-entry. #### Max duration A time-entry cannot have a duration longer than 24h00 (ie one full day). #### Cut at midnight A time-entry cannot overlap 2 different days (example `startsAt = 18:00:00` and `duration = 10:00:00`). It should be two distinct time-entries cut at `00:00:00`. #### Mandatory axisSection on activity timesheets A time-entry must have axisSection if the corresponding timesheet is in activity mode, and vice-versa. #### Inactive axisSection A time-entry cannot be modified if one of its axisSection is no longer active (`active=false`). #### Incompatible axisSections A time-entry cannot have nested axisSections that does not meet a correct parent-child tree structure. ## Fields examples: - id: 552586 ownerId: 90 owner: id: 90 name: Hélène Girard url: https://example.ilucca.net/api/v3/timesheetusers/90 unit: 2 startsAt: '2024-04-22T09:30:00' duration: '03:45:00' endsAt: '2024-04-22T13:15:00' authorId: 90 createdAt: '2024-07-04T11:59:51.09' modifierId: 90 modifiedAt: '2024-07-04T17:00:54.4' archivedAt: null creationSource: 2 layer: 0 axisSections: - id: 41 name: Conception url: https://example.ilucca.net/api/v3/axissections/41 - id: 127 name: Animal Logic url: https://example.ilucca.net/api/v3/axissections/127 - id: 346 name: 'Projet Rose : KPI - tableau de bord' url: https://example.ilucca.net/api/v3/axissections/346 - id: 347 name: Art Direction url: https://example.ilucca.net/api/v3/axissections/347 comment: id: 59 name: This is a comment url: https://example.ilucca.net/api/v3/timeentrycomments/59 timeTypeId: null timesheetId: 10967 timesheet: id: 10967 name: 90 - avril 2024 - Submitted url: https://example.ilucca.net/api/v3/timmitimesheets/10967 x-tags: - TimeEntries properties: id: type: integer minimum: 1 description: Unique identifier for this object. readOnly: true ownerId: type: integer minimum: 1 description: Reference to the time-entry owner. example: 199 owner: $ref: '#/components/schemas/TimesheetUser' description: The owner of this time-entry. unit: type: integer enum: - 0 - 1 - 2 example: 2 description: |- Unit in which the time-entry has been entered. - 0: Days (eg "1/2 day") - 1: Hours (eg "8h15min") - 2: Time (eg "23:45:00") startsAt: type: string format: date-time description: >- The timeEntry start date and time. Please do NOT send any offset/timezone information ("Z", "+01:00", etc...). example: '2022-01-01T08:00:00' duration: type: string format: timespan default: '00:00:00' example: '03:45:00' description: "Duration of the time-entry in the\_\"c\" format of a C# timespan In other words : d.hh:mm:ss.\nMax: \"1.00:00:00\" (ie 24 hours)." endsAt: type: string format: date-time description: Automatically set as startsAs + duration when editing a timeentry. example: '2022-01-01T11:45:00' readOnly: true authorId: type: integer description: Identifier of the user who initially created this time-entry. example: 199 readOnly: true createdAt: type: string format: date-time description: >- Date and time when time-entry was first created. (Central European Time) example: '2022-01-01T18:35:10' readOnly: true modifierId: type: integer description: The unique identifier of the user who last updated the time-entry. readOnly: true modifiedAt: type: string description: >- Date and time when time-entry was last modified. (Central European Time). The time-entry is modified by any change made to the time-entry, including when corresponding timesheet is sent for approbation (status=1) and when the timesheet is completely approved (status=2). format: date-time example: '2022-01-01T18:42:14' readOnly: true archivedAt: type: string description: >- Date and time when time-entry was deleted (Central European Time). When null, implies that the time-entry still has not been deleted (and maybe never will). format: date-time example: '2022-01-01T18:41:12' readOnly: true creationSource: type: integer enum: - 0 - 1 - 2 - 3 description: >- Attribute used to identify last modification source : - 0: Automatic fallback on theoretical time-entries from workcycles. - 1: Entered with Lucca Timesheet quick-fill tools. - 2: Manually created or edited (default). - 3: Imported from external sources. Is read-only on Lucca Timesheet user interfaces only if Timesheet regulation is in following modes : attendance schedule with clock-in clock-out, and activity schedule. - 4: Entered with Lucca Timesheet clock-in clock-out tool. default: 2 layer: type: integer description: >- Used to store the original workcycle at the time of time-entry modification. In 99.999% of use cases, you will want the 0 : Actual time-entry. - 0: Actual time-entry. - 1: Theoretical workcycle. readOnly: true axisSections: type: - array - 'null' description: >- Represent the activities that time-entry should be associated with. When not in activity mode, send an empty array, or do not serialize this property. items: $ref: '#/components/schemas/AxisSection' comment: type: - 'null' - object description: >- A comment to add additional information about the given time-entry. It will be visible on Lucca Timesheet user interface. properties: id: type: integer readOnly: true content: type: string description: Comment content authorId: type: integer description: Identifier of the user who initially created this comment readOnly: true createdAt: type: string format: date-time description: >- Date and time when the comment was first created. (Central European Time) readOnly: true timeTypeId: type: - integer - 'null' description: >- Optional reference of a configured Time Type. To use only if the timesheet is set up to use Time Types. Null otherwise. timesheetId: type: integer description: >- The reference to the timeshet this timeentry is associated with when the timesheet is at least sent for approval. Is null if the timesheet is still pending submission. readOnly: true required: - ownerId - unit - startsAt - duration TimesheetUser: title: Timesheet User type: object properties: id: type: integer minimum: 1 description: Unique identifier of this User. firstName: type: string description: Given name. lastName: type: string description: Family name mail: type: string format: email description: Email address. legalEntityId: type: integer description: >- Unique identifier of the legal establishment this user currently has a work contract with. description: A Timesheet limited model of a user AxisSection: title: The AxisSection resource type: object properties: id: type: integer minimum: 1 code: type: string readOnly: true name: type: string readOnly: true multilingualName: type: string readOnly: true description: type: string readOnly: true ownerId: type: integer minimum: 1 readOnly: true startOn: type: string format: date-time readOnly: true endOn: type: string format: date-time readOnly: true active: type: boolean readOnly: true axisId: type: integer readOnly: true parentAxisSections: type: array items: type: object description: Axis-section objects readOnly: true childrenAxisSections: type: array items: type: object description: Axis-section objects readOnly: true x-tags: - TimeEntries description: >- You can [read more about this resource here](/api-reference/legacy/organization/axis-sections/get-started). responses: ResponseProblem: description: Problem content: application/json: schema: type: object properties: Status: type: integer description: HTTP status code. example: 401 Message: type: string description: Human readable error message. example: Unauthorized ````