Track changes with delta

This guide walks you through the delta workflow to retrieve only new or changed records from the Protime API since your last request.

Before you begin

• Obtain a valid access token. See Authenticate.
• Required scopes: a .read scope for the target collection (e.g. connector-protimeapi-clockings.read).
• Only one delta can be active per collection at a time.
• See Delta synchronization for background on how change tracking works.

Step 1: Start a delta request with an initial filter

Add &delta as a query parameter to your standard GET list request.

Response (first page):

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

The initial delta response is always paginated. You must walk through all pages before a deltaLink appears.

Step 2: Navigate through all pages using nextLink

Follow each nextLink until you reach the last page. The last page contains a deltaLink instead of a nextLink.

Response (last page):

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

Step 3: Retrieve delta changes

Use the deltaLink from the previous response to fetch only the changes since your last request.

Response:

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

Delta change responses are not paginated – all changes are returned in a single response along with a new deltaLink.

Step 4: Continue tracking changes

Store the latest deltaLink from each response and use it for your next request. Repeat Step 3 on your desired schedule.

Handle the changeVersion field

Each object in a delta response includes a changeVersion string. If you receive a record whose changeVersion is older than one you already processed (same ID), ignore the older one. The changeVersion supports string comparison for ordering.

Include external references in delta requests

Append externalReferences to the initial delta request:

GET /connector/protimeapi/api/v1/clockings?filter=date%20ge%20'2025-12-01'&delta&externalReferences=(people,@badge-number) HTTP/1.1
Host: <tenant>.myprotime.eu

Related

• Delta reference – delta properties, token format, and expiration rules
• Delta synchronization – why delta exists and design rationale
• Fetch resources – standard filtering and pagination