Time and Attendance

Timesheets endpoint overview, data structure, validation, time zones, payable hours, approvals, breaks, and API usage.

Beta Feature: This endpoint is currently in beta. Please reach out to our support team if you need assistance with implementation.

Overview

The timesheets endpoint allows you to retrieve attendance data from HRIS systems and convert them into a unified data model. Each timesheet represents work time tracking for a single employee, delivered in a consistent data structure regardless of the underlying HRIS system.

Key Use Cases

• Monitor employee attendance and working hours
• Verify if employees worked their expected hours
• Process payroll data with approved timesheets
• Track break times and compliance
• Generate attendance reports

Prerequisites

Important: Timesheets are employee-centric, so you must include employees in your integration scope to properly sync timesheet data.

• Default sync period: The Last 2 months of timesheets get synced
• Employee filtering: When employee filters are applied, only filtered employees’ timesheets are synced

For the full API data model and all query/filter options, see the GET timesheets endpoint.

Understanding Timesheet Data Structure

Complete vs Incomplete Timesheets

Timesheets can exist in various states of completion depending on the employee’s clocking behavior and system reliability:

Complete Timesheet (Ideal scenario)

{
  "started_at": "2025-04-16T09:02:00.000Z",
  "ended_at": "2025-04-16T16:59:00.000Z",
  "payable_hours": 8
}

Incomplete Timesheets

Start time only:

{
  "started_at": "2025-04-16T09:02:00.000Z",
  "ended_at": null,
  "payable_hours": null
}

End time only:

{
  "started_at": null,
  "ended_at": "2025-04-16T16:59:00.000Z",
  "payable_hours": null
}

• Open timesheet: Missing end time, could indicate ongoing work or system issues
  • Start time only: Employee clocked in but hasn’t clocked out (may still be working)
  • End time only: Clock-in wasn’t registered, only clock-out recorded
• Sync updates: Incomplete timesheets are often updated and completed during the next sync cycle once the employee clocks out

If timesheets remain incomplete or validation issues persist, reach out to your customer with the specific employee name and timesheet times so they can correct the data in their HRIS system. After the next full sync, the corrected data should be properly reflected.

Timesheet Overlap Validation

Important rule: timesheets cannot overlap for the same employee.

• ❌ Invalid: Timesheet from 09:00–17:00 and another from 16:00–19:00 has a 1-hour overlap
• ✅ Valid: Timesheet from 09:00–12:00 and another from 13:00–17:00 with no overlap

When overlapping timesheets are detected:

• Sync continues but generates warnings
• We won’t upsert the overlapping timesheet
• This can indicate a issue or wrong timesheet in the HRIS

Open Timesheet Validation

• An open timesheet, without an end time, cannot exist within the time range of a closed timesheet
• Multiple consecutive open timesheets are allowed since they do not have defined end boundaries

Time Zones and Time Handling

All timesheet times are provided in UTC format for consistency, along with the local timezone offset:

{
  "started_at": "2025-04-16T09:02:00.000Z",
  "ended_at": "2025-04-16T16:59:00.000Z",
  "timezone": "-04:00"
}

Implementation tip: Use the timezone offset to display times in the employee’s local timezone in your UI.

Timezone awareness is essential for accurate approvals and schedule comparisons:

• Always show the employee’s local time alongside UTC when reviewing/approving.
• The timezone field is an ISO‑8601 offset (e.g., -04:00) captured for that shift. Use it to reconstruct the shift’s local time historically. Do not recompute using your current local offset — DST changes between then and now can happen.
• When comparing scheduled vs. received times, convert both into the same local timezone (either the schedule’s zone or the record’s offset) before comparing.
• Respect local day boundaries. If a shift crosses midnight, compare by local day if your policies are day-based.

Payable Hours Logic

{
  "payable_hours": 8,
  "started_at": "2025-04-16T09:02:00.000Z",
  "ended_at": "2025-04-16T16:59:00.000Z"
}

payable_hours is never auto-calculated by Kombo. This value comes directly from the HRIS system.

Grace Periods

Payable hours may differ from calculated work time due to grace periods:

• Employee starts 5 minutes late, for example 07:05 instead of 07:00
• Grace period allows full pay despite late start
• payable_hours reflects the grace period adjustment
• If payable_hours is null, the HRIS does not support this feature

Fallback Calculation

When payable_hours is null, meaning the HRIS doesn’t support this feature, you can calculate payable hours using: end_time - start_time - unpaid_break_minutes. This provides a reasonable approximation for payroll purposes when grace period data is not available.

This calculation is at your own risk, as the HRIS system might still apply grace periods or overtime calculations that aren’t exposed through the API. Your calculated values may differ from the official payroll figures.

Approval Workflow

Approval Status

{
  "approval_status": "APPROVED",
  "approved_at": "2025-04-16T17:05:31.000Z"
}

Use cases:

• Payroll processing: Only process approved timesheets
• Manager oversight: Identify pending approvals
• Compliance: Track approval timestamps for audit trails

Break Time Implementation Patterns

Break handling varies significantly across HRIS systems. Check the coverage grid for system-specific support levels.

Need implementation support?\

Break patterns can vary across HRIS systems and use cases. If you need guidance on implementing break logic for your specific requirements, our support team is ready to help. Reach out to schedule a call where we can discuss the best approach for your integration.

Break data rules:

• Only complete breaks, with both start and end times, are included
• Open breaks are never accepted and won’t be upserted, but we will show a warning.
• unpaid_break_minutes is calculated from unpaid breaks or provided directly by the HRIS

Detailed break tracking

{
  "started_at": "2025-04-16T09:00:00.000Z",
  "ended_at": "2025-04-16T17:00:00.000Z",
  "unpaid_break_minutes": 90,
  "breaks": [
    {
      "started_at": "2025-04-16T12:00:00.000Z",
      "ended_at": "2025-04-16T13:00:00.000Z",
      "paid": false
    },
    {
      "started_at": "2025-04-16T15:00:00.000Z",
      "ended_at": "2025-04-16T15:30:00.000Z",
      "paid": false
    }
  ]
}

Detailed Break Tracking

API Usage Examples

Basic Timesheet Retrieval

GET /hris/timesheets?employee_id=H77fDF8uvEzGNPRubiz5DvQ7

Date Range Filtering

GET /hris/timesheets?started_after=2025-04-01T00:00:00.000Z&ended_before=2025-04-30T23:59:59.000Z

Implementation Best Practices

1. Handle multiple break patterns
   • Parse detailed break arrays when available
   • Fall back to break minutes calculation
   • Detect break periods from split timesheets
2. Timezone considerations
   • Always store times in UTC
   • Use timezone offsets for display purposes
   • Consider employee location for compliance reporting
3. Error handling
   • Handle cases where payable_hours is null
   • Account for missing break data
   • Plan for partial timesheet data
4. Filtering and performance
   • Use date range filters to limit data volume
   • Implement pagination for large datasets
   • Filter by specific employees when possible

Common Integration Scenarios

Payroll Processing

1. Filter timesheets by approval status, for example APPROVED
2. Use payable_hours when available, otherwise calculate from time ranges
3. Factor in unpaid_break_minutes for accurate pay calculations
4. Verify approval timestamps meet payroll cutoff requirements

Attendance Monitoring

1. Check for incomplete timesheets that are missing start or end times
2. Monitor for unusual patterns such as very short or very long shifts
3. Track break compliance based on company policies
4. Generate alerts for timesheet anomalies