Retrieve a clocking

Collections

Clockings

Retrieve a clocking

Introduction

You can retrieve a clocking by the internal ID using the GET call. The IDs are available in the location header after a successful POST call for creating a clocking.

Tip

Check the Swagger page for more technical information on the endpoints.

Endpoint details

GET

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

URL parameters

This parameter needs to be filled in when calling this endpoint.

Parameter	Description
`<id>`	The internal ID of the clocking. IDs are available in the location header after a successful POST call.

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`).

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

With an external reference

An example with ID 657 and the employee number as external reference for the person.

GET

GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings/657?externalReferences=(people,@employee-number)

Create a clocking Retrieve a list