Retrieve a delta

Reference

Collections

Clockings

Retrieve a delta

Returns clockings that have changed since the last delta token.

Caution

Read the Delta page. There is important information on required implementation!

Tip

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

Endpoint details

GET

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?delta

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

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	—	Read-only	Internal ID of the person who performed the clocking.
`date`	string	—	Read-only	Date of the clocking (YYYY-MM-DD).
`timeOfDayInMinutes`	integer	—	Read-only	Minutes since midnight (-1440 and 2880) representing the time of the clocking on the specified date.
`terminal.id`	integer	—	Read-only	Internal ID of the terminal on which the clocking occurred.
`geolocation.longitude`	number	—	Read-only	Longitude coordinate where the clocking was registered.
`geolocation.latitude`	number	—	Read-only	Latitude coordinate where the clocking was registered.
`reason.id`	integer	—	Read-only	Internal ID of the reason for the clocking (only present if `kind` is `Reason`).
`isOpen`	boolean	—	Read-only	Indicates if the reason clocking is open (only present if `kind` is `Reason`).
`activityLevels`	array	—	Read-only	Array of activity levels, each with a `level` and an `activityDefinition.id` (only present if `kind` is `Activity`).
`kind`	string	—	Read-only	Type of clocking (`InOut`, `Reason`, `Activity`, `ActivityEnd`, or `NotSupported` for a clocking type that the API does not expose).

Important

A soft-deleted clocking appears with "changeType": "InsertOrUpdate" and "status": "Deleted", not with "changeType": "Delete". Check both fields to detect every deletion. See Soft-deleted clockings.

Filters

Filter	Type	Description
`date`	Required	The start date must be a recent date in the past, with the earliest allowed start date being January 1st of the previous year
`kind`	Optional	Filter by clocking kind (`InOut`, `Reason`, `Activity`, `ActivityEnd`)

Note

The person filter cannot be combined with delta: a delta always covers all people. A request with both returns 400 Bad Request.
The start date must be a recent date in the past, with the earliest allowed start date being January 1st of the previous year
The end date isn’t required, when providing an end date there is a max range of 1 year
Clocking kinds are optional

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
`terminals`	`@external-code`	Supported
`activity-definitions`	`@data-entry-code`, `@external-reference`	Supported
`absence-definitions`	`@absence-code`	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
`410`	Delta token has expired (older than 72 hours)
`414`	Request URI too long

Examples

A delta with date and external reference

Example for clockings with a delta starting from 1st of January 2025 and employee number as external reference for people:

GET

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=date ge '2025-01-01'&externalReferences=(people,@employee-number)&delta

Retrieve a list of clockings Webhooks