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
GET
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. |
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. |
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. |
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. |
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. |
kind |
string | Yes | Yes | Type of clocking (InOut, Reason, Activity, ActivityEnd). |
isOpen |
boolean | No | Yes | Indicates whether the reason clocking is open. Only applicable when kind is Reason. |
reason.id |
integer | No | Yes | Internal ID of the reason for the clocking (only present if 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). |
status |
string | — | Read-only | Status of the clocking (Unknown, Active, Deleted). |
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 |
The requested clocking kind is not yet supported |
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:
GET
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:
GET
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings/657?externalReferences=(people,@employee-number)