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 | — | Read-only | 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 | — | Read-only | 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 custom external references for the entity type being queried. See the external references page for details and the predefined options list.
Each history type endpoint supports external references for its own entity collection only:
| History type | Supported collection | Predefined | Custom |
|---|---|---|---|
department-histories |
departments |
None | Supported |
employer-histories |
employers |
None | Supported |
job-histories |
jobs |
None | Supported |
job-category-histories |
job-categories |
None | Supported |
sector-histories |
sectors |
None | Supported |
work-location-histories |
work-locations |
None | Supported |
Note
The people collection with @badge-number and @employee-number predefined references is only available on the per-person endpoint, not on this list endpoint.
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