Retrieve a clocking
Returns a single clocking by its internal ID. The ID is available in the Location header after a successful POST call.
Tip
Check the Swagger page for more technical information on the endpoints.
Endpoint details
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings/{id}
Headers: Authorization: Bearer {token}, User-Agent: {agent}
Scope: connector-protimeapi-clockings.read
URL parameters
| Parameter | Description |
|---|---|
{id} |
The internal ID of the clocking. IDs are available in the location header after a successful POST call. |
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 clocking. |
calculatedTimeOfDayInMinutes |
integer | — | Read-only | The time of day in minutes after any corrections or calculations. |
isGenerated |
boolean | — | Read-only | Indicates if the clocking was generated by the system. |
originalTimeOfDayInMinutes |
integer | — | Read-only | Original time of the clocking as registered by the terminal or input source. Only present if the clocking has been edited. |
status |
string | — | Read-only | Status of the clocking (Unknown, Active, Deleted). |
person.id |
integer | Yes | Yes | Internal ID of the person who performed the clocking. |
date |
string | Yes | Yes | Date of the clocking (YYYY-MM-DD). |
timeOfDayInMinutes |
integer | Yes | Yes | Minutes since midnight (-1440 to 2880) representing the time of the clocking on the specified date. |
terminal.id |
integer | No | Yes | Internal ID of the terminal on which the clocking occurred. |
geolocation.longitude |
number | No | Yes | Longitude coordinate where the clocking was registered. |
geolocation.latitude |
number | No | Yes | Latitude coordinate where the clocking was registered. |
reason.id |
integer | No | Yes | Internal ID of the reason for the clocking (only present if kind is Reason). |
isOpen |
boolean | No | Yes | Indicates whether the reason clocking is open. Only applicable when kind is Reason. |
activityLevels |
array | No | Yes | Array of activity levels, each with a level and an activityDefinition.id (only present if kind is Activity). |
kind |
string | Yes | Yes | Type of clocking (InOut, Reason, Activity, ActivityEnd). Responses contain NotSupported for a clocking type that the API does not expose. |
Note
A soft-deleted clocking is still returned, with "status": "Deleted". See Soft-deleted clockings.
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 |
terminals |
@external-code |
Supported |
activity-definitions |
@data-entry-code, @external-reference |
Supported |
absence-definitions |
@absence-code |
Supported |
Caution
There are some restrictions on the characters allowed in URL requests. See the fetching resources page for more information.
Error responses
| Status | Condition |
|---|---|
400 |
Invalid external reference specification |
401 |
Missing or invalid access token, or insufficient scope |
404 |
Clocking with the given ID does not exist |
Examples
Retrieving a clocking
Example with clocking ID 657:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings/657
With an external reference
Example with the employee number as external reference for the person:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings/657?externalReferences=(people,@employee-number)