Retrieve a delta
Returns the historical field records of one category 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
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/{HistoricalFieldCategoryIdentifier}-histories?delta
Headers: Authorization: Bearer {token}, User-Agent: {agent}
Scope: connector-protimeapi-people-historical-data.read
Note
The initial request also accepts connector-protimeapi-people.read, but the deltaLink endpoint does not. A token that only carries connector-protimeapi-people.read receives 401 Unauthorized when following the deltaLink.
URL parameters
| Parameter | Description |
|---|---|
{HistoricalFieldCategoryIdentifier} |
The identifier of the historical field category (see table below). |
Response properties
| Field | Type | Required | Writable | Description |
|---|---|---|---|---|
id |
integer | — | Read-only | Internal unique identifier for the historical field record. |
changeVersion |
string | — | Read-only | Property to indicate the order of changes. |
person.id |
integer | — | Read-only | Internal unique identifier for the person. |
until |
string | — | Read-only | End date of the historical field record (YYYY-MM-DD). Not returned while the record is still active. |
<category>.id |
integer | — | Read-only | Internal unique identifier for the related entity. The field name depends on the category (see table below). |
from |
string | — | Read-only | Start date of the historical field record (YYYY-MM-DD). |
Department history records list their properties in the order person, id, changeVersion, until, from, department.
Historical field categories
| Category | Identifier | Delta endpoint path | Response field name |
|---|---|---|---|
| departments | department | connector/protimeapi/api/v1/delta/department-histories |
department.id |
| employers | employer | connector/protimeapi/api/v1/delta/employer-histories |
employer.id |
| jobs | job | connector/protimeapi/api/v1/delta/job-histories |
job.id |
| job categories | job-category | connector/protimeapi/api/v1/delta/job-category-histories |
jobCategory.id |
| sectors | sector | connector/protimeapi/api/v1/delta/sector-histories |
sector.id |
| work locations | work-location | connector/protimeapi/api/v1/delta/work-location-histories |
workLocation.id |
Filters
This endpoint does not support filters. A delta always covers all historical field records of the category in the URL. A request that includes the filter query parameter is rejected with 400 Bad Request, both when starting a delta (?delta) and when following a deltaLink.
External references
The endpoint supports predefined and custom external references. See the external references page for details and the predefined options list.
Each history type supports the people collection and its own entity collection:
| History type | Supported collections | Predefined | Custom |
|---|---|---|---|
department-histories |
people, departments |
@badge-number, @employee-number (people only) |
Supported |
employer-histories |
people, employers |
@badge-number, @employee-number (people only) |
Supported |
job-histories |
people, jobs |
@badge-number, @employee-number (people only) |
Supported |
job-category-histories |
people, job-categories |
@badge-number, @employee-number (people only) |
Supported |
sector-histories |
people, sectors |
@badge-number, @employee-number (people only) |
Supported |
work-location-histories |
people, work-locations |
@badge-number, @employee-number (people only) |
Supported |
The externalReferences query parameter of the initial request is carried over into the deltaLink.
Error responses
| Status | Condition |
|---|---|
400 |
Unsupported query parameter, such as filter, or an invalid external reference |
401 |
Missing or invalid access token, or insufficient scope |
410 |
Delta token has expired (older than 72 hours) |
414 |
Request URI too long |
Examples
Retrieving delta changes for department histories with an external reference
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/department-histories?delta&externalReferences=(people,@employee-number)
Retrieving delta changes for employer histories
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/employer-histories?delta