Clocking model
Time representation
All clocking endpoints express time as minutes since midnight in the timeOfDayInMinutes field. Standard values range from 0 (midnight) to 1439 (23:59). The extended range from -1440 to 2880 is used when a clocking is explicitly placed on a previous or next day.
| Value range | Meaning |
|---|---|
| -1440 to -1 | A time on the previous day |
| 0 to 1439 | A normal time on the specified day |
| 1440 to 2880 | A time on the next day |
Overnight clockings
Workforce management frequently involves shifts that cross midnight. The Protime API supports two approaches for handling these clockings.
Standard approach (recommended)
When the schedules in Protime are configured for night shifts, the integrator sends clockings with the actual clock time expressed in the normal range (0–1439). Protime determines the correct day based on the schedule configuration.
For example, an employee clocking in at 22:00 on 13 February (timeOfDayInMinutes: 1320) and out at 06:00 on 14 February (timeOfDayInMinutes: 360) results in two standard clockings. The schedule configuration assigns both to 14 February automatically.
This is the expected approach for most integrations.
Override approach
In rare cases, the integrator needs to explicitly control which day a clocking belongs to by using extended time values. A value of 1800 (06:00 next day) or -120 (22:00 previous day) overrides the schedule configuration.
Caution
Only use extended time values when the schedule configuration cannot determine the correct day. The standard approach is sufficient for the vast majority of integrations.
Soft-deleted clockings
When a clocking is manually deleted in Protime, it is not physically removed from the system. Instead, the clocking remains with a "status": "Deleted" value. The API includes soft-deleted clockings in all responses – list, delta, and webhook events.
In delta responses, a soft-deleted clocking appears with "changeType": "InsertOrUpdate" and "status": "Deleted". This is distinct from a physical deletion, which uses "changeType": "Delete". Integrators should check both the changeType and status fields to correctly handle all deletion scenarios.
Clocking kinds
Each clocking record carries a kind field that determines its purpose:
| Kind | Description |
|---|---|
InOut |
Standard check-in or check-out registration |
Reason |
A clocking associated with an absence or special reason |
Activity |
A clocking that starts an activity registration with one or more levels |
ActivityEnd |
A clocking that ends the currently active activity |
Further reading
- Create a clocking – request body, fields, and examples for creating clockings
- Retrieve a list of clockings – filtering and response format
- Delta synchronization – how change tracking works across all collections
- Your first clocking integration – end-to-end tutorial for building a clocking integration
- Create, update, and delete resources – practical steps for writing data through the API