Retrieve a list
Returns a list of historical field records for all people, for one historical field category.
Tip
Check the Swagger page for more technical information on the endpoints.
Endpoint details
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/{HistoricalFieldCategoryIdentifier}-histories
Headers: Authorization: Bearer {token}, User-Agent: {agent}
Scope: connector-protimeapi-people.read or connector-protimeapi-people-historical-data.read
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 | Yes | Yes | Internal unique identifier for the related entity. The field name depends on the category (see table below). |
from |
string | Yes | Yes | 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
The options for currently supported historical field categories are the following:
| Category | Identifier | Response field name |
|---|---|---|
| departments | department | department.id |
| employers | employer | employer.id |
| jobs | job | job.id |
| job categories | job-category | jobCategory.id |
| sectors | sector | sector.id |
| work locations | work-location | workLocation.id |
Filters
This endpoint does not support filters. It always returns all historical field records of the category in the URL. A request that includes the filter query parameter is rejected with 400 Bad Request.
To retrieve the historical fields of one person, use Retrieve historical fields.
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 endpoint 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 |
Note
On this endpoint the people reference only enriches the person property of each record. It cannot be used to select a person — use the per-person endpoint for that.
Error responses
| Status | Condition |
|---|---|
400 |
Unsupported query parameter, such as filter |
401 |
Missing or invalid access token, or insufficient scope |
414 |
Request URI too long (continuation token) |
Examples
Retrieve all department histories
Example to retrieve the history of departments for the whole population:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/department-histories
Retrieve all employer histories
Example to retrieve the history of employers for the whole population:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/employer-histories