Retrieve a list
Introduction
You can retrieve a list of clockings using a filter.
Tip
Check the Swagger page for more technical information on the endpoints.
Endpoint details
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings
Response properties
This list of properties is returned by this endpoint.
| Property | Type | Description |
|---|---|---|
changeVersion |
string | Property to indicate the order of changes. |
id |
integer | Unique identifier for the clocking. |
person.id |
integer | Internal ID of the person who performed the clocking. |
date |
string | Date of the clocking (YYYY-MM-DD). |
timeOfDayInMinutes |
integer | Minutes since midnight (-1440 and 2880) representing the time of the clocking on the specified date. |
originalTimeOfDayInMinutes |
integer | Original time of the clocking as registered by the terminal or input source. Only present if the clocking has been edited. |
calculatedTimeOfDayInMinutes |
integer | The time of day in minutes after any corrections or calculations. |
isGenerated |
boolean | Indicates if the clocking was generated by the system. |
terminal.id |
integer | Internal ID of the terminal on which the clocking occurred. |
geolocation.longitude |
number | Longitude coordinate where the clocking was registered. |
geolocation.latitude |
number | Latitude coordinate where the clocking was registered. |
kind |
string | Type of clocking (InOut, Reason, Activity, ActivityEnd). |
reason.id |
integer | Internal ID of the reason for the clocking (only present if kind is Reason). |
activityLevels |
array | Array of activity levels, each with a level and an activityDefinition.id (only present if kind is Activity). |
status |
string | Status of the clocking (Unknown, Active, Deleted). |
Filters
This list of filters can be used for this endpoint. Some filters are mandatory.
| Filter | Type | Description |
|---|---|---|
person |
Optional | Filter by specific person IDs |
date |
Required | Date range (required with max of 1 year range) |
kind |
Optional | Filter by clocking kind (InOut, Reason, Activity, ActivityEnd) |
Check the Fetching Resources page on how to use the filter.
External references
It’s possible to use predefined external references and custom external references. More information can be found on the External References Page
For a list of predefined external references, see the external reference options section.
Note
Check the query options below the endpoint on the Swagger page for the relevant external references.
Good to know
Overnight clockings
The Protime API supports handling overnight clockings. Clocking data is imported on the correct day, based on the configuration of the schedule within Protime.
In most cases, clockings are created with normal time values (0–1439 minutes since midnight), and the schedule configuration determines on which day the clocking appears. For example, a check-in at 22:00 (timeOfDayInMinutes: 1320) on 13 February might be assigned to 14 February if the day schedule is configured that way for night shifts.
In responses, you may see timeOfDayInMinutes values in the extended range from -1440 to 2880 when a clocking has been explicitly placed on a previous or next day. Refer to the Create a clocking page for a detailed explanation of both scenarios.
Soft-deleted clockings
Note
Soft-deleted clockings are included in the responses. These are clockings that have been manually deleted but remain in the system with a “Deleted” status.
In responses, soft-deleted records appear as:
"status": "Deleted"indicating whether a clocking is active or soft-deleted.
Example of a soft-delete in a response:
{
"changeVersion": "0001E7C5000098FA0013",
"id": 657,
"calculatedTimeOfDayInMinutes": 600,
"isGenerated": false,
"status": "Deleted",
"person": {
"id": 7478
},
"date": "2025-01-01",
"timeOfDayInMinutes": 600,
"terminal": {
"id": 214
},
"geolocation": {
"longitude": 4.486493,
"latitude": 51.013541
},
"kind": "InOut"
}Examples
Filter on date range with external reference
Example with a date range and the employee number as the external reference for people:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=date ge '2025-01-01' and date le '2026-01-01'&externalReferences=(people,@employee-number)
Filter on people in organisational groups
Example with a filter on a few people, a date range and the InOut kind as well as the employee number as the external reference:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=person in org-group (200,201) and date ge '2024-01-01' and date le '2024-01-05'
Filter on people, date range, a kind with external reference
Example with a filter on a few people, a date range and the InOut kind as well as the employee number as the external reference:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=person in (1,2,3) and date ge '2024-01-01' and date le '2024-01-05' and kind eq 'InOut' &externalReferences=(people,@employee-number)