Retrieve a list

Returns a filtered list of assignments.

Endpoint details

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

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

Response properties

Field	Type	Required	Writable	Description
changeVersion	string	—	Read-only	Property to indicate the order of changes.
id	integer	—	Read-only	Internal unique identifier for the assignment.
person.id	integer	Yes	Yes	Internal ID of the person who the assignment is for.
from	string	Yes	Yes	Start date of the assignment (YYYY-MM-DD).
until	string	No	Yes	End date of the assignment (YYYY-MM-DD).
startTimeInMinutes	integer	No	Yes	Start time in minutes since midnight.
endTimeInMinutes	integer	No	Yes	End time in minutes since midnight.
breakDurationInMinutes	integer	No	Yes	Duration of the break in minutes.
comments	string	No	Yes	Comments associated with the assignment.
activityLevels.level	integer	Yes	Yes	A list of levels in the activity structure of the registered activity definition.
activityLevels.activityDefinition.id	string	Yes	Yes	Unique identifier for the activity definition registered.
isRejected	boolean	—	Read-only	Whether the assignment has been rejected.

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). Filters assignments based on the from date property.

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
activity-definitions	@data-entry-code, @external-reference	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:

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

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/assignments?filter=date ge '2025-01-01' and date le '2025-01-31'&externalReferences=(people,@employee-number)

Filter on people and date range

Example with a filter on specific people and a date range:

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/assignments?filter=person in (1,2,3) and date ge '2025-01-01' and date le '2025-01-31'

Filter on people in organisational groups

Example with a filter on people in organisational groups and a date range:

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

Filter on people and date range with multiple external references

Example with a filter on a few people, a date range and multiple external references:

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