Timesheet Management APIs¶
The Timesheet Management APIs provide functionality for time tracking, approval workflows, and timesheet operations in the Stratpoint Timesheet Application. These APIs are designed for business-specific operations with user-centric endpoints and comprehensive approval workflows.
Authentication Headers¶
All timesheet management endpoints require authentication:
Timelog Operations¶
Get Timelogs for User¶
Retrieves timelogs for a specific user within a date range.
/api/v2/timelogs/{userId}/{startDate}/{endDate}/{clientLastSyncTime?}
Parameters:
- userId: User ID (required)
- startDate: Start date in YYYY-MM-DD format (required)
- endDate: End date in YYYY-MM-DD format (required)
- clientLastSyncTime: Optional client sync timestamp
Permission Required: Permission ID 57 (or 72 for viewing other users)
Response:
{
"header": {
"status": 200,
"title": "Timelog",
"description": "Data Successfully Retrieved"
},
"body": {
"data": [
{
"id": 12345,
"user_id": 123,
"projectUser_id": 456,
"tasktype_id": 1,
"startTime": "2024-01-15 09:00:00",
"stopTime": "2024-01-15 17:00:00",
"spentHours": "8.00",
"description": "Development work on authentication module",
"status": "Approved",
"approverUserId": 999,
"isProcessable": true,
"isEditable": false,
"day": "2024-01-15",
"project": {
"id": 789,
"name": "Client Portal Development",
"client": "ABC Corporation"
},
"tasktype": {
"id": 1,
"title": "Development"
}
}
],
"meta": {
"totalHours": "40.00",
"approvedHours": "32.00",
"pendingHours": "8.00"
}
}
}
Create Timelog Entry¶
Creates a new timelog entry.
/api/v2/timelogs
Request Body:
{
"user_id": 123,
"projectUser_id": 456,
"tasktype_id": 1,
"subtasktype_id": 2,
"startTime": "2024-01-15 09:00:00",
"stopTime": "2024-01-15 17:00:00",
"description": "Development work on authentication module",
"isProcessable": true
}
Response:
{
"header": {
"status": 200,
"title": "Timelog",
"description": "Data Successfully Saved"
},
"body": {
"data": {
"id": 12346,
"user_id": 123,
"projectUser_id": 456,
"spentHours": "8.00",
"status": "For_Approval",
"created_at": "2024-01-15T10:30:00Z"
}
}
}
Update Timelog Entry¶
Updates an existing timelog entry.
/api/v2/timelogs/{id}
Request Body:
{
"startTime": "2024-01-15 09:30:00",
"stopTime": "2024-01-15 17:30:00",
"description": "Updated development work on authentication module with JWT implementation"
}
Delete Timelog Entry¶
Deletes a timelog entry.
/api/v2/timelogs/{id}
Response:
{
"header": {
"status": 200,
"title": "Timelog",
"description": "Data Successfully Deleted"
},
"body": {
"data": {
"id": 12345,
"deleted_at": "2024-01-15T11:30:00Z"
}
}
}
Timelog Approval Workflows¶
Change Timelog Status (Approve/Reject)¶
Approves or rejects timelog entries with support for bulk operations.
/api/v2/timelogs/changeStatus
Permission Required: Permission ID 103 (timelog approval)
Request Body for Approval:
Request Body for Rejection:
{
"id": "12345,12346",
"status": "Rejected",
"rejectReasonType": "Re-classify to Other Charge Code",
"note": {
"note": "Please reclassify this work as internal training",
"rejectReasonType": "Re-classify to Other Charge Code"
}
}
Validation Rules:
- id: Required, comma-separated timelog IDs
- status: Required, one of: For_Approval, Approved, Rejected
- rejectReasonType: Required if status is Rejected, one of:
- Employee on Leave
- Re-classify to Other Charge Code
- Others
- note: Required if status is Rejected
Response:
{
"header": {
"status": 200,
"title": "Timelog",
"description": "Status Successfully Changed"
},
"body": {
"data": {
"processedCount": 3,
"approvedCount": 3,
"rejectedCount": 0,
"processedIds": [12345, 12346, 12347]
}
}
}
Time Reports and Analytics¶
Get Task Calendar Data¶
Retrieves timelog data formatted for calendar display.
/api/v2/timelogs/getTaskCalendarData/{userId}/{startDate}/{endDate}
Parameters:
- userId: User ID (required)
- startDate: Start date in YYYY-MM-DD format (required)
- endDate: End date in YYYY-MM-DD format (required)
Response:
{
"header": {
"status": 200,
"title": "Timelog",
"description": "Data Successfully Retrieved"
},
"body": {
"data": [
{
"id": 12345,
"title": "Development - 8.0h",
"start": "2024-01-15",
"backgroundColor": "#3498db",
"borderColor": "#2980b9",
"textColor": "#ffffff",
"extendedProps": {
"timelogId": 12345,
"projectName": "Client Portal Development",
"hours": "8.00",
"status": "Approved"
}
}
]
}
}
Get Total Logged Hours Per Day¶
Retrieves daily hour summaries for a user.
/api/v2/timelogs/getTotalLoggedHoursPerDay/{userId}/{startDate}/{endDate}/{clientLastSyncTime?}
Response:
{
"header": {
"status": 200,
"title": "Timelog",
"description": "Data Successfully Retrieved"
},
"body": {
"data": [
{
"day": "2024-01-15",
"totalHours": "8.00",
"approvedHours": "8.00",
"pendingHours": "0.00",
"rejectedHours": "0.00"
},
{
"day": "2024-01-16",
"totalHours": "7.50",
"approvedHours": "0.00",
"pendingHours": "7.50",
"rejectedHours": "0.00"
}
]
}
}
User Weekly Report¶
Retrieves weekly timelog summary for a user.
/api/v2/timelogs/userWeeklyReport/{userId}
Response:
{
"header": {
"status": 200,
"title": "Timelog",
"description": "Data Successfully Retrieved"
},
"body": {
"data": {
"weeklyHours": "40.00",
"targetHours": "40.00",
"utilization": 100.0,
"breakdown": [
{
"projectName": "Client Portal Development",
"hours": "32.00",
"percentage": 80.0
},
{
"projectName": "Internal Training",
"hours": "8.00",
"percentage": 20.0
}
]
}
}
}
User Detailed Task Report¶
Retrieves detailed timelog report for a user.
/api/v2/timelogs/userDetailedTaskReport
Request Body:
{
"userId": 123,
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"projectId": 456,
"status": "Approved"
}
Response:
{
"header": {
"status": 200,
"title": "Timelog",
"description": "Data Successfully Retrieved"
},
"body": {
"data": [
{
"date": "2024-01-15",
"projectName": "Client Portal Development",
"taskName": "Development",
"description": "Authentication module implementation",
"hours": "8.00",
"status": "Approved"
}
],
"summary": {
"totalHours": "160.00",
"totalDays": 20,
"averageHoursPerDay": "8.00"
}
}
}
Approver Detailed Task Report¶
Retrieves detailed report for timelog approvers.
/api/v2/timelogs/approverDetailedTaskReport
Permission Required: Permission ID 72 (approver permissions)
Request Body:
{
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"status": "For_Approval",
"userId": 123,
"projectId": 456
}
Export Approver Detailed Task Report¶
Exports timelog approval report in specified format.
/api/v2/timelogs/exportApproverDetailedTaskReport/{extension}
Parameters:
- extension: File format (csv, xlsx, pdf)
Response:
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="timelog_report_2024-01-31.xlsx"
[binary file data]
CTO (Compensatory Time Off) Management¶
Get Available Offsets¶
Retrieves available CTO hours for a user.
/api/v2/timelogs/offsets/available/{userId}/{returnArray?}
Parameters:
- userId: User ID (required)
- returnArray: Optional, returns array format if set to 1
Response:
{
"header": {
"status": 200,
"title": "Timelog",
"description": "Data Successfully Retrieved"
},
"body": {
"data": [
{
"id": 456,
"sourceTimelogId": 12345,
"userId": 123,
"hours": "4.00",
"earnedDate": "2024-01-10",
"expiryDate": "2024-07-10",
"isUsed": 0,
"usedDate": null,
"description": "Overtime work on project deadline"
}
],
"summary": {
"totalAvailableHours": "16.00",
"expiringSoonHours": "4.00",
"expiryDate": "2024-07-10"
}
}
}
Report Offset References¶
Reports on CTO usage and references.
/api/v2/timelogs/reportOffsetReferences
Request Body:
Get Night Differential Payout Report¶
Retrieves night differential compensation report.
/api/v2/timelogs/getNightDifferentialPayoutReport
Request Body:
Business Rules and Constraints¶
Last Year Timelog Handling¶
Timelogs for the previous year are subject to special middleware validation:
- Route group:
timesheet.timelogs.handlelastyear - Prevents modifications to old timelog entries
- Applied to all CRUD operations on timelogs resource
Status Values¶
Timelog Status:
- For_Approval: Pending approval
- Approved: Approved by supervisor
- Rejected: Rejected with reason
Rejection Reason Types:
- Employee on Leave: Employee was on leave during logged time
- Re-classify to Other Charge Code: Work should be charged to different project/task
- Others: Other rejection reasons
Permission Requirements¶
Basic Timelog Operations: - Permission 57: View own timelogs - Permission 72: View all user timelogs
Approval Operations: - Permission 103: Approve/reject timelogs
Special Operations: - Permission for specific report types - Permission for CTO management
Error Handling¶
Validation Errors¶
Common Validation Rules:
{
"header": {
"status": 412,
"title": "Timelog",
"description": "Validation error encountered"
},
"body": {
"errors": {
"startTime": ["The start time field is required"],
"description": ["The description must be at least 10 characters"]
}
}
}
Access Control Errors¶
{
"header": {
"status": 401,
"title": "Timelog",
"description": "Access not allowed"
},
"body": []
}
Key Implementation Notes¶
- User-Centric Design: Most endpoints require explicit userId parameters
- Business Logic Integration: Complex approval workflows and business rules
- Permission-Based Access: Granular permissions for different operations
- Bulk Operations: Support for comma-separated IDs in approval operations
- Date Range Requirements: Most queries require explicit date ranges
- Status-Based Workflow: Structured approval process with specific status values
- Integration with Projects: Timelogs linked to specific project assignments
- CTO Management: Comprehensive overtime compensation tracking
This timesheet management API is designed for enterprise-level time tracking with comprehensive approval workflows and business rule enforcement.