Collections
Clockings
Retrieve a list

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

GET
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 day program within Protime.

Note

The timeOfDayInMinutes property supports values from -1440 up to 2880. This allows you to register clockings that occur before midnight (previous day) or after midnight (next day), which is especially useful for night shifts and overnight clockings.

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:

GET
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:

GET
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:

GET
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)

Retrieve a clockingRetrieve a delta