Retrieve historical fields
Returns the historical field records for a specific person, 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/people/{PersonReference}/{HistoricalFieldCategoryIdentifier}-history
Headers: Authorization: Bearer {token}, User-Agent: {agent}
Scope: connector-protimeapi-people.read or connector-protimeapi-people-historical-data.read
URL parameters
These parameters need to be filled in when calling this endpoint.
| Parameter | Description |
|---|---|
<PersonReference> |
The internal ID or external reference of the person. |
<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 |
External references
The endpoint supports predefined and custom external references. See the external references page for details.
The following collections are supported for this endpoint:
| Collection | Predefined | Custom |
|---|---|---|
people |
@badge-number, @employee-number |
Supported |
departments |
None | Supported |
employers |
None | Supported |
jobs |
None | Supported |
job-categories |
None | Supported |
sectors |
None | Supported |
work-locations |
None | Supported |
Note
The available entity collection for external references depends on the history type being queried. For example, when querying department-history, the departments collection is available.
Caution
There are some restrictions on the characters allowed in URL requests. See the fetching resources page for more information.
Error responses
| Status | Condition |
|---|---|
400 |
Invalid external reference key or value |
401 |
Missing or invalid access token, or insufficient scope |
404 |
Person with the given ID or external reference does not exist |
Examples
Retrieving department history for a person
Example to request the history of departments for person 1238:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people/1238/department-history
Retrieving employer history for a person
Example to request the history of employers for person 1238:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people/1238/employer-history