Delta

General information

The Delta allows you to retrieve changes (deltas) from the Protime API since your last request. It helps reduce the volume of data by fetching only new or updated records. Note that only one delta can be active at a time in a specific collection.

Tip

Check the Swagger page to see which collections are available in the delta section.

Maintenance

Caution

  • A delta needs regular maintenance because it expires after 72 hours. Once expired, the delta data is deleted and cannot be retrieved.
  • Even if the delta endpoint returns an empty list, it will contain a deltaLink. This new deltaLink must be used to ensure it remains valid within the 72-hour expiration period.
  • In the response, each object (e.g., Clocking object) includes a changeVersion field. This field is crucial for determining whether a newly received object is more recent than a previously received one. If the changeVersion of a newly received object is older than the changeVersion of a previously received object with the same unique identifier, the new object can be ignored. Note that the changeVersion field supports string comparison for determining its relative value.

Delta expiration and handling

If an expired deltalink is used it will return an error 410 Gone. This indicates that the delta is no longer available and a new delta request needs to be started.

Properties

Property Type Description
changeType string The type of data change (InsertOrUpdate, Delete).
data.changeVersion string The version identifier for the change. Should be used to correctly process order of changes.
data.... various types The data of the object that was requested (e.g. clocking, person etc.)
deltaLink string A new link to obtain the new data changes in a next request.

External references

It’s possible to use external references within the use of a delta.
Check the Collections page for the use of predefined external references or the External references page to use custom external references.

Example for clockings with an external reference(badge number):
GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=date ge '2025-12-01'&delta&externalReferences=(people,@badge-number)

Start a delta request

To start a delta request, add the delta as a query parameter to your GET List endpoint.

The response of this endpoint is always paginated. You must navigate through all pages using the nextLink to retrieve all initial data before a deltaLink will appear on the last page of the paginated response.

Example of a last page with deltaLink:

//GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/<resource-collection>?delta
{
  "value": [
    ...
    ],
  "deltaLink": "/connector/protimeapi/api/v1/delta/clockings?deltaToken=eyJEZWx0YUlkIjozMDA4MCwiU3RhcnRpbmdDdXJzb3IiOjQ1NTIyLCJUaW1lU3RhbXAiOiIyMDI1LTAxLTEwVDEzOjMxOjE0LjE2Njk3NjhaIn0="
}

Tip

Check the Collections page to use the correct filters. These may vary across different collections.

Retrieve delta changes

Use the deltaLink provided in the previous delta response to continue fetching changes with the Delta endpoint listed in Swagger.

When retrieving delta changes, pagination does not apply. All changes since your last request will be returned in a single response, along with a new deltaLink for the next request.

Example of a delta response:

//GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/delta/<resource-collection>?deltaToken=eyJEZWx0YUlkIjozMDA4MCwiU3RhcnRpbmdDdXJzb3IiOjQ1NTIyLCJUaW1lU3RhbXAiOiIyMDI1LTAxLTEwVDEzOjMxOjE0LjE2Njk3NjhaIn0=

{ 
  "value": [
    {
      "changeType": "InsertOrUpdate",
      "data": {
        "changeVersion": "0000090200004BD0000A",
        "id": 18618,
        "date": "2025-01-10",
        ...
      }
    },
    ...
    ],
  "deltaLink": "/connector/protimeapi/api/v1/delta/clockings?deltaToken=eyJEZWx0YUlkIjozMDA4MCwiU3RhcnRpbmdDdXJzb3IiOjQ1NTIyLCJUaW1lU3RhbXAiOiIyMDI1LTAxLTEwVDEzOjMxOjE0LjE2Njk3NjhaIn0="
}
  • <value>
    • Contains a list of all data changes for the requested collection
  • <ChangeType>
    • The type of data change. Possible values are InsertOrUpdate or Delete
  • <data>
    • The actual object. Has the same layout as described in the collection.
  • <deltaLink>
    • A new link to obtain the new data changes.