> For the complete documentation index, see [llms.txt](https://api-docs.myhappyforce.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.myhappyforce.com/docs/api-reference/timesheet.md).

# Timesheet

## PUT /api/v1/employee/timesheet/{timesheetId}

> Update a timesheet record

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"TimesheetUpdateRequestDTO":{"type":"object","description":"Timesheet update data","properties":{"startTime":{"type":"string","format":"date-time","description":"Start date and time of the work period in UTC"},"endTime":{"type":"string","format":"date-time","description":"End date and time of the work period in UTC"},"periodType":{"$ref":"#/components/schemas/PeriodTimeSheetType","description":"Type of period: ACTIVE, VACATION, BANK_HOLIDAY, SICK_LEAVE, INDISPOSITION_ABSENCE, or DAY_OFF"},"changeReason":{"type":"string","description":"Reason for updating this timesheet record","minLength":1},"timeZone":{"type":"string","description":"IANA timezone ID for this update (e.g. Europe/Madrid). Stored on the timesheet document; start/end times above are still stored as UTC.","minLength":1}},"required":["changeReason","timeZone"]},"PeriodTimeSheetType":{"type":"string","description":"Type of timesheet period (active work, vacation, bank holiday, sick leave, indisposition absence, day off)","enum":["ACTIVE","VACATION","BANK_HOLIDAY","SICK_LEAVE","INDISPOSITION_ABSENCE","DAY_OFF"]},"PersonTimesheetDTO":{"type":"object","description":"DTO representing a person's timesheet entry","properties":{"id":{"type":"string","description":"Timesheet entry ID"},"personId":{"type":"string","description":"Person ID"},"startTime":{"type":"string","format":"date-time","description":"Start time of the timesheet entry"},"endTime":{"type":"string","format":"date-time","description":"End time of the timesheet entry"},"isActive":{"type":"boolean","description":"Whether the timesheet entry is currently active"},"isEditable":{"type":"boolean","description":"Whether the timesheet entry can be edited"},"breaks":{"type":"array","description":"List of break times during this timesheet entry","items":{"$ref":"#/components/schemas/PersonTimesheetBreakDTO"}},"periodType":{"$ref":"#/components/schemas/PeriodTimeSheetType","description":"Type of timesheet period"},"timeZone":{"type":"string","description":"IANA timezone ID stored for this entry when provided by the client"},"changeHistory":{"type":"array","description":"Historical modifications applied to this timesheet entry","items":{"$ref":"#/components/schemas/PersonTimesheetChangeDTO"}}}},"PersonTimesheetBreakDTO":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"duration":{"type":"integer","format":"int32"}}},"PersonTimesheetChangeDTO":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"breaks":{"type":"array","items":{"$ref":"#/components/schemas/PersonTimesheetBreakDTO"}},"periodType":{"$ref":"#/components/schemas/PeriodTimeSheetType"},"changeReason":{"type":"string"},"changedBy":{"type":"string"},"changedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/api/v1/employee/timesheet/{timesheetId}":{"put":{"tags":["Timesheet"],"description":"Update a timesheet record","operationId":"updateTimesheet","parameters":[{"name":"timesheetId","in":"path","description":"Timesheet ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimesheetUpdateRequestDTO"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonTimesheetDTO"}}}}}}}}}
```

## POST /api/v1/employee/timesheet/{employeeId}/start

> Start work time for an employee

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"TimesheetDateTimeRequestDTO":{"type":"object","description":"Request body for timesheet start/end/break operations with a single date-time in ISO-8601 format","properties":{"dateTime":{"type":"string","description":"Date and time in ISO-8601 format (e.g. 2024-01-15T09:00:00Z)"},"timeZone":{"type":"string","description":"IANA timezone ID for this operation (e.g. Europe/Madrid). Stored on the timesheet document; dateTime is still interpreted as a UTC instant.","minLength":1}},"required":["dateTime","timeZone"]}}},"paths":{"/api/v1/employee/timesheet/{employeeId}/start":{"post":{"tags":["Timesheet"],"description":"Start work time for an employee","operationId":"startWorkTime","parameters":[{"name":"employeeId","in":"path","description":"Employee ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimesheetDateTimeRequestDTO"}}},"required":true},"responses":{"200":{"description":"OK"}}}}}}
```

## POST /api/v1/employee/timesheet/{employeeId}/end

> End work time for an employee

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"TimesheetDateTimeRequestDTO":{"type":"object","description":"Request body for timesheet start/end/break operations with a single date-time in ISO-8601 format","properties":{"dateTime":{"type":"string","description":"Date and time in ISO-8601 format (e.g. 2024-01-15T09:00:00Z)"},"timeZone":{"type":"string","description":"IANA timezone ID for this operation (e.g. Europe/Madrid). Stored on the timesheet document; dateTime is still interpreted as a UTC instant.","minLength":1}},"required":["dateTime","timeZone"]}}},"paths":{"/api/v1/employee/timesheet/{employeeId}/end":{"post":{"tags":["Timesheet"],"description":"End work time for an employee","operationId":"endWorkTime","parameters":[{"name":"employeeId","in":"path","description":"Employee ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimesheetDateTimeRequestDTO"}}},"required":true},"responses":{"200":{"description":"OK"}}}}}}
```

## POST /api/v1/employee/timesheet/{employeeId}/break/start

> Start break time for an employee

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"TimesheetDateTimeRequestDTO":{"type":"object","description":"Request body for timesheet start/end/break operations with a single date-time in ISO-8601 format","properties":{"dateTime":{"type":"string","description":"Date and time in ISO-8601 format (e.g. 2024-01-15T09:00:00Z)"},"timeZone":{"type":"string","description":"IANA timezone ID for this operation (e.g. Europe/Madrid). Stored on the timesheet document; dateTime is still interpreted as a UTC instant.","minLength":1}},"required":["dateTime","timeZone"]}}},"paths":{"/api/v1/employee/timesheet/{employeeId}/break/start":{"post":{"tags":["Timesheet"],"description":"Start break time for an employee","operationId":"startBreak","parameters":[{"name":"employeeId","in":"path","description":"Employee ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimesheetDateTimeRequestDTO"}}},"required":true},"responses":{"200":{"description":"OK"}}}}}}
```

## POST /api/v1/employee/timesheet/{employeeId}/break/end

> End break time for an employee

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"TimesheetDateTimeRequestDTO":{"type":"object","description":"Request body for timesheet start/end/break operations with a single date-time in ISO-8601 format","properties":{"dateTime":{"type":"string","description":"Date and time in ISO-8601 format (e.g. 2024-01-15T09:00:00Z)"},"timeZone":{"type":"string","description":"IANA timezone ID for this operation (e.g. Europe/Madrid). Stored on the timesheet document; dateTime is still interpreted as a UTC instant.","minLength":1}},"required":["dateTime","timeZone"]}}},"paths":{"/api/v1/employee/timesheet/{employeeId}/break/end":{"post":{"tags":["Timesheet"],"description":"End break time for an employee","operationId":"endBreak","parameters":[{"name":"employeeId","in":"path","description":"Employee ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimesheetDateTimeRequestDTO"}}},"required":true},"responses":{"200":{"description":"OK"}}}}}}
```

## GET /api/v1/employee/timesheet/{employeeId}/state

> Get timesheet state for an employee

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"PersonTimesheetDTO":{"type":"object","description":"DTO representing a person's timesheet entry","properties":{"id":{"type":"string","description":"Timesheet entry ID"},"personId":{"type":"string","description":"Person ID"},"startTime":{"type":"string","format":"date-time","description":"Start time of the timesheet entry"},"endTime":{"type":"string","format":"date-time","description":"End time of the timesheet entry"},"isActive":{"type":"boolean","description":"Whether the timesheet entry is currently active"},"isEditable":{"type":"boolean","description":"Whether the timesheet entry can be edited"},"breaks":{"type":"array","description":"List of break times during this timesheet entry","items":{"$ref":"#/components/schemas/PersonTimesheetBreakDTO"}},"periodType":{"$ref":"#/components/schemas/PeriodTimeSheetType","description":"Type of timesheet period"},"timeZone":{"type":"string","description":"IANA timezone ID stored for this entry when provided by the client"},"changeHistory":{"type":"array","description":"Historical modifications applied to this timesheet entry","items":{"$ref":"#/components/schemas/PersonTimesheetChangeDTO"}}}},"PersonTimesheetBreakDTO":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"duration":{"type":"integer","format":"int32"}}},"PeriodTimeSheetType":{"type":"string","description":"Type of timesheet period (active work, vacation, bank holiday, sick leave, indisposition absence, day off)","enum":["ACTIVE","VACATION","BANK_HOLIDAY","SICK_LEAVE","INDISPOSITION_ABSENCE","DAY_OFF"]},"PersonTimesheetChangeDTO":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"breaks":{"type":"array","items":{"$ref":"#/components/schemas/PersonTimesheetBreakDTO"}},"periodType":{"$ref":"#/components/schemas/PeriodTimeSheetType"},"changeReason":{"type":"string"},"changedBy":{"type":"string"},"changedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/api/v1/employee/timesheet/{employeeId}/state":{"get":{"tags":["Timesheet"],"description":"Get timesheet state for an employee","operationId":"getTimesheetState","parameters":[{"name":"employeeId","in":"path","description":"Employee ID","required":true,"schema":{"type":"string"}},{"name":"date","in":"query","description":"Date to get timesheet state (format: ddMMyyyy)","required":true,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonTimesheetDTO"}}}}}}}}}
```

## GET /api/v1/employee/timesheet/{employeeId}/records

> Get timesheet records for a specific month

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"PaginableGenericListResultPersonTimesheetDTO":{"type":"object","properties":{"from":{"type":"integer","format":"int32"},"to":{"type":"integer","format":"int32"},"total":{"type":"integer","format":"int32"},"noContent":{"type":"boolean"},"results":{"type":"array","items":{"$ref":"#/components/schemas/PersonTimesheetDTO"}}}},"PersonTimesheetDTO":{"type":"object","description":"DTO representing a person's timesheet entry","properties":{"id":{"type":"string","description":"Timesheet entry ID"},"personId":{"type":"string","description":"Person ID"},"startTime":{"type":"string","format":"date-time","description":"Start time of the timesheet entry"},"endTime":{"type":"string","format":"date-time","description":"End time of the timesheet entry"},"isActive":{"type":"boolean","description":"Whether the timesheet entry is currently active"},"isEditable":{"type":"boolean","description":"Whether the timesheet entry can be edited"},"breaks":{"type":"array","description":"List of break times during this timesheet entry","items":{"$ref":"#/components/schemas/PersonTimesheetBreakDTO"}},"periodType":{"$ref":"#/components/schemas/PeriodTimeSheetType","description":"Type of timesheet period"},"timeZone":{"type":"string","description":"IANA timezone ID stored for this entry when provided by the client"},"changeHistory":{"type":"array","description":"Historical modifications applied to this timesheet entry","items":{"$ref":"#/components/schemas/PersonTimesheetChangeDTO"}}}},"PersonTimesheetBreakDTO":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"duration":{"type":"integer","format":"int32"}}},"PeriodTimeSheetType":{"type":"string","description":"Type of timesheet period (active work, vacation, bank holiday, sick leave, indisposition absence, day off)","enum":["ACTIVE","VACATION","BANK_HOLIDAY","SICK_LEAVE","INDISPOSITION_ABSENCE","DAY_OFF"]},"PersonTimesheetChangeDTO":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"breaks":{"type":"array","items":{"$ref":"#/components/schemas/PersonTimesheetBreakDTO"}},"periodType":{"$ref":"#/components/schemas/PeriodTimeSheetType"},"changeReason":{"type":"string"},"changedBy":{"type":"string"},"changedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/api/v1/employee/timesheet/{employeeId}/records":{"get":{"tags":["Timesheet"],"description":"Get timesheet records for a specific month","operationId":"getTimesheetRecordsForMonth","parameters":[{"name":"employeeId","in":"path","description":"Employee ID","required":true,"schema":{"type":"string"}},{"name":"startDate","in":"query","description":"Start date (format: ddMMyyyy)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"endDate","in":"query","description":"End date (format: ddMMyyyy)","required":true,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginableGenericListResultPersonTimesheetDTO"}}}}}}}}}
```

## GET /api/v1/employee/timesheet/{employeeId}/history

> Get timesheet history for an employee

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"PeriodTimesheetDTO":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"byPersonTimeSheet":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/PersonTimesheetDTO"}}},"totalCount":{"type":"integer","format":"int64"}}},"PersonTimesheetDTO":{"type":"object","description":"DTO representing a person's timesheet entry","properties":{"id":{"type":"string","description":"Timesheet entry ID"},"personId":{"type":"string","description":"Person ID"},"startTime":{"type":"string","format":"date-time","description":"Start time of the timesheet entry"},"endTime":{"type":"string","format":"date-time","description":"End time of the timesheet entry"},"isActive":{"type":"boolean","description":"Whether the timesheet entry is currently active"},"isEditable":{"type":"boolean","description":"Whether the timesheet entry can be edited"},"breaks":{"type":"array","description":"List of break times during this timesheet entry","items":{"$ref":"#/components/schemas/PersonTimesheetBreakDTO"}},"periodType":{"$ref":"#/components/schemas/PeriodTimeSheetType","description":"Type of timesheet period"},"timeZone":{"type":"string","description":"IANA timezone ID stored for this entry when provided by the client"},"changeHistory":{"type":"array","description":"Historical modifications applied to this timesheet entry","items":{"$ref":"#/components/schemas/PersonTimesheetChangeDTO"}}}},"PersonTimesheetBreakDTO":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"duration":{"type":"integer","format":"int32"}}},"PeriodTimeSheetType":{"type":"string","description":"Type of timesheet period (active work, vacation, bank holiday, sick leave, indisposition absence, day off)","enum":["ACTIVE","VACATION","BANK_HOLIDAY","SICK_LEAVE","INDISPOSITION_ABSENCE","DAY_OFF"]},"PersonTimesheetChangeDTO":{"type":"object","properties":{"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"breaks":{"type":"array","items":{"$ref":"#/components/schemas/PersonTimesheetBreakDTO"}},"periodType":{"$ref":"#/components/schemas/PeriodTimeSheetType"},"changeReason":{"type":"string"},"changedBy":{"type":"string"},"changedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/api/v1/employee/timesheet/{employeeId}/history":{"get":{"tags":["Timesheet"],"description":"Get timesheet history for an employee","operationId":"getTimesheetHistory","parameters":[{"name":"employeeId","in":"path","description":"Employee ID","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","description":"Pagination offset","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"to","in":"query","description":"Pagination limit","required":false,"schema":{"type":"integer","format":"int32","default":10}},{"name":"dateFrom","in":"query","description":"Start date filter (format: ddMMyyyy)","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"dateTo","in":"query","description":"End date filter (format: ddMMyyyy)","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeriodTimesheetDTO"}}}}}}}}}
```
