Retrieve a list

Returns a filtered list of hours to validate requests.

Endpoint details

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/hours-to-validate-requests

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

Response properties

Field	Type	Required	Writable	Description
changeVersion	string	—	Read-only	Property to indicate the order of changes.
id	string	—	Read-only	Unique identifier (GUID) for the hours to validate request.
person.id	integer	—	Read-only	Internal ID of the person the request applies to.
date	string	—	Read-only	Date the requested hours are registered on (YYYY-MM-DD).
durations	array	—	Read-only	The durations covered by the request.
durations[].id	integer	—	Read-only	Identifier of the requested duration.
durations[].startTimeInMinutes	integer	—	Read-only	Start time of the requested duration (minutes since midnight, between -1440 and 2880). Omitted when the duration is not bound to a start time.
durations[].endTimeInMinutes	integer	—	Read-only	End time of the requested duration (minutes since midnight, between -1440 and 2880). Omitted when the duration is not bound to an end time.
durations[].durationInMinutes	integer	—	Read-only	Requested duration, in minutes.
durations[].originalDurationInMinutes	integer	—	Read-only	Duration before the request was raised, in minutes.
status	string	—	Read-only	Status of the request. Possible values: Uninitialized, Requested, Deleted, Approved, Refused. An approved request results in a validated hours record.
requested.person.id	integer	—	Read-only	Internal ID of the person who raised the request. This can differ from person.id.
requested.requestedAt	string	—	Read-only	Date and time the request was raised (ISO 8601 format).
isStale	boolean	—	Read-only	Indicates that the request is based on hours to validate that have since been recalculated to a different amount. A stale request can no longer be approved or refused, only deleted.
conversation	array	—	Read-only	Comments exchanged on the request. Omitted when no comments were made.
conversation[].person.id	integer	—	Read-only	Internal ID of the person who made the comment.
conversation[].commentedAt	string	—	Read-only	Date and time the comment was made (ISO 8601 format).
conversation[].comment	string	—	Read-only	Text of the comment.

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 a max of 1 year range)

Both a start and an end date are required. Check the Fetching Resources page on how to use the filter.

Pagination

This endpoint supports pagination via continuationToken. The response includes a nextLink field when more results are available. Pass the continuationToken value as a query parameter to retrieve the next page.

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

External references are resolved on person, requested.person and conversation[].person.

Error responses

Status	Condition
400	Invalid filter syntax, unknown filter field, missing date filter, 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

Examples

Filter on date range

Example with a date range:

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/hours-to-validate-requests?filter=date ge '2025-01-01' and date le '2025-01-31'

Filter on people and a date range with external reference

Example with people, a date range and the employee number as an external reference:

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/hours-to-validate-requests?filter=person in (123,456) and date ge '2025-01-01' and date le '2025-01-31'&externalReferences=(people,@employee-number)

Filter on people in organisational groups

Example with the people of two organisational groups and a date range:

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/hours-to-validate-requests?filter=person in org-group (200,201) and date ge '2025-01-01' and date le '2025-01-31'

Related pages

• Retrieve an hours to validate request
• Retrieve a delta of hours to validate requests