Retrieve a list

Returns a filtered list of counter instances.

Endpoint details

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

Headers: Authorization: Bearer {token}, User-Agent: {agent} Scope: connector-protimeapi-counters.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 counter instance.
shiftDefinition.id	integer	—	Read-only	Unique identifier for the shift definition, if a shift is linked to this counter.
numberOfInstances	integer	—	Read-only	Number of counter instances.
request.id	string	—	Read-only	Internal unique identifier for the related request, if the counter was requested.
status	string	—	Read-only	Status of the counter instance (Unknown, Auto, Manual, Calendar).
isAuthorized	boolean	—	Read-only	Indicates if the counter instance is authorized.
person.id	integer	—	Read-only	Unique identifier for the person linked to this counter.
periodType	string	—	Read-only	Type of period the counter applies to (Unknown, Day, Week, PayPeriod).
counterDefinition.id	integer	—	Read-only	Unique identifier for the counter definition linked to this counter.
date	string	—	Read-only	Date of the counter instance that it is registered on.
startTimeInMinutes	integer	—	Read-only	Start time in minutes from midnight.
endTimeInMinutes	integer	—	Read-only	End time in minutes from midnight.
durationInMinutes	integer	—	Read-only	Duration of the counter instance in minutes.

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)
counter-definition	Optional	Filter by specific counter definition IDs
status	Optional	Filter by one or more status values

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 and the predefined options list.

The following collections are supported for this endpoint:

Collection	Predefined	Custom
people	@badge-number, @employee-number	Supported
shift-definitions	@shift-code	Supported
counter-definitions	@counter-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

Example with a date range between the 1st of January 2025 and 5th of January 2025:

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/counters?filter=date ge '2025-01-01' and date le '2025-01-05'

Filter on people and date range with external reference

Example with people and counter code:

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/counters?filter=person in (1,2,3) and date ge '2025-01-01' and date le '2025-01-05' &externalReferences=(people,@employee-number)(counter-definitions,@counter-code)