Retrieve a list
Returns a list of historical field records for all people, filtered by 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. |
from |
string | Yes | Yes | Start date of the historical field record (YYYY-MM-DD). |
until |
string | — | Read-only | End date of the historical field record (YYYY-MM-DD). Null when 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). |
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 require any filter parameters. It returns all historical fields in the system.
Note
People cannot be filtered in this endpoint. To retrieve historical fields for a specific person, use the single person endpoint.
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 |
|---|---|
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