Retrieve a list of clockings

Returns a filtered list of clockings.

Endpoint details

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings

Headers: Authorization: Bearer {token}, User-Agent: {agent} Scope: connector-protimeapi-clockings.read

Response properties

Field	Type	Required	Writable	Description
changeVersion	string	—	Read-only	Property to indicate the order of changes.
id	integer	—	Read-only	Unique identifier for the clocking.
calculatedTimeOfDayInMinutes	integer	—	Read-only	The time of day in minutes after any corrections or calculations.
isGenerated	boolean	—	Read-only	Indicates if the clocking was generated by the system.
originalTimeOfDayInMinutes	integer	—	Read-only	Original time of the clocking as registered by the terminal or input source. Only present if the clocking has been edited.
status	string	—	Read-only	Status of the clocking (Unknown, Active, Deleted).
person.id	integer	Yes	Yes	Internal ID of the person who performed the clocking.
date	string	Yes	Yes	Date of the clocking (YYYY-MM-DD).
timeOfDayInMinutes	integer	Yes	Yes	Minutes since midnight (-1440 and 2880) representing the time of the clocking on the specified date.
terminal.id	integer	No	Yes	Internal ID of the terminal on which the clocking occurred.
geolocation.longitude	number	No	Yes	Longitude coordinate where the clocking was registered.
geolocation.latitude	number	No	Yes	Latitude coordinate where the clocking was registered.
reason.id	integer	No	Yes	Internal ID of the reason for the clocking (only present if kind is Reason).
isOpen	boolean	No	Yes	Indicates if the reason clocking is open (only present if kind is Reason).
activityLevels	array	No	Yes	Array of activity levels, each with a level and an activityDefinition.id (only present if kind is Activity).
kind	string	Yes	Yes	Type of clocking (InOut, Reason, Activity, ActivityEnd). Responses contain NotSupported for a clocking type that the API does not expose.

Filters

Filter	Type	Description
person	Optional	Internal person IDs (person in (1, 2, 3)), or the current members of circles (person in circle(2, 8)) or org-groups (person in org-group(121, 122)). When omitted, all people are returned.
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

The endpoint supports predefined and custom external references. See the external references page for details.

The following collections are supported for this endpoint:

Collection	Predefined	Custom
people	@badge-number, @employee-number	Supported
terminals	@external-code	Supported
activity-definitions	@data-entry-code, @external-reference	Supported
absence-definitions	@absence-code	Supported

Error responses

Status	Condition
400	Invalid filter syntax, unknown filter field, or a person filter combined with delta
401	Missing or invalid access token, or insufficient scope
409	The people matched by the person filter changed between pages
414	Request URI too long (filter + continuation token)

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)