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.

Maintenance

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

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):

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="
}

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.

Complete delta flow example

Below is a step-by-step example demonstrating the complete delta workflow from initial request to retrieving changes.

Step 1: Start a delta request with initial filter

Make your first request to the collection endpoint with the delta query parameter:

Response (first page):

{
  "value": [
    {
      "id": 1001,
      "date": "2024-12-01",
      "changeVersion": "0000090200004BD0000A",
      ...
    },
    ...
  ],
  "nextLink": "/connector/protimeapi/api/v1/clockings?filter=date ge '2024-12-01'&continuationToken=eyJ2YWxpZGF0aW9uSGFzaCI6MCwiaW50ZXJuYWxTZXJ2aWNlS2V5U2V0IjoiVzNzaVZHRmliR1ZCYkdsaGN5STZJbkVpTENKR2FXVnNaQ0k2SWxKRlExOU9VaUlzSWxaaGJIVmxJam94TkRBM01ERXdNWDFkIn0=&deltaToken=eyJkZWx0YUlkIjo2NzcsInN0YXJ0aW5nQ3Vyc29yIjowLCJ0aW1lU3RhbXAiOiIyMDI1LTExLTI1VDEyOjU3OjM2LjM3OTE3NDhaIn0="
}

Step 2: Navigate through all pages using nextLink

Continue following the nextLink until you reach the last page:

Response (last page):

{
  "value": [],
  "deltaLink": "/connector/protimeapi/api/v1/delta/clockings?deltaToken=eyJkZWx0YUlkIjo2NzcsInN0YXJ0aW5nQ3Vyc29yIjowLCJ0aW1lU3RhbXAiOiIyMDI1LTExLTI1VDEyOjU3OjM2LjM3OTE3NDhaIn0="
}

Step 3: Retrieve delta changes

Use the deltaLink from the previous response to fetch changes:

Response:

{
  "value": [
    {
      "changeType": "InsertOrUpdate",
      "data": {
        "id": 1050,
        "date": "2024-12-02",
        "changeVersion": "0000090200004BD0000B",
        ...
      }
    },
    {
      "changeType": "Delete",
      "data": {
        "id": 1001,
        "changeVersion": "0000090200004BD0000C"
      }
    }
  ],
  "deltaLink": "/connector/protimeapi/api/v1/delta/clockings?deltaToken=eyJkZWx0YUlkIjo2NzcsInN0YXJ0aW5nQ3Vyc29yIjoxMjM0LCJ0aW1lU3RhbXAiOiIyMDI1LTExLTI1VDEzOjMwOjAwLjAwMDAwMDBaIn0="
}

Step 4: Continue tracking changes

Keep using the new deltaLink from each response to retrieve subsequent changes. Remember to call the delta endpoint at least once every 72 hours to prevent expiration, even if no changes are expected.