Delta

This page documents the delta specification for the Protime API, including delta properties, expiration rules, response structure, supported collections, and external reference support.

For step-by-step instructions, see How to track changes with delta. For background on the synchronization model, see Delta synchronization.

Delta endpoint URL pattern

Delta responses are served from a dedicated path:

connector/protimeapi/api/v1/delta/{collection}?deltaToken={token}

The {collection} segment matches the name of the source collection (e.g. clockings, people).

Delta properties

Delta token format

The deltaToken query parameter is a Base64-encoded JSON object with the following fields:

The token is opaque to consumers and is produced and validated by the API. Consumers pass it back unchanged via the deltaToken query parameter.

Delta expiration

• A delta expires 72 hours after the last request.
• Once expired, the delta data is deleted and cannot be retrieved.
• An expired delta link returns 410 Gone.
• Even when the delta endpoint returns an empty list, the response contains a new deltaLink. Using that new link keeps the delta valid within the 72-hour window.

changeVersion comparison

The changeVersion field supports string comparison for determining relative ordering. If a newly received object has a changeVersion that is lexicographically smaller than a previously received object with the same unique identifier, the newer receipt can be safely ignored.

Concurrency constraint

Only one delta can be active at a time per collection.

Initial request vs. subsequent requests

Initial request response structure

The initial delta request is always paginated. Pages are linked via nextLink until a deltaLink appears on the last page.

Last page example:

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

Subsequent delta response structure

{
    "value": [
        {
            "changeType": "InsertOrUpdate",
            "data": {
                "changeVersion": "0000090200004BD0000A",
                "id": 18618,
                "date": "2025-01-10"
            }
        },
        {
            "changeType": "Delete",
            "data": {
                "id": 1001,
                "changeVersion": "0000090200004BD0000C"
            }
        }
    ],
    "deltaLink": "/connector/protimeapi/api/v1/delta/clockings?deltaToken=eyJEZWx0YUlkIjozMDA4MCwiU3RhcnRpbmdDdXJzb3IiOjQ1NTIyLCJUaW1lU3RhbXAiOiIyMDI1LTAxLTEwVDEzOjMxOjE0LjE2Njk3NjhaIn0="
}

Response fields

Supported collections

The following collections support delta tracking:

External references with delta

External references can be included in delta requests by appending the externalReferences query parameter.

Example – clockings with badge number:

See the external references reference for details on predefined and custom external references.

See also

• How to track changes with delta
• Delta synchronization