Update a historical field
Moves an existing historical field entry to a different start date.
Tip
Check the Swagger page for more technical information on the endpoints.
Endpoint details
PUT
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people/{personReference}/{historicalFieldCategoryIdentifier}-history
Headers: Authorization: Bearer {token}, User-Agent: {agent}
Scope: connector-protimeapi-people.write or connector-protimeapi-people-historical-data.write
URL parameters
| Parameter | Description |
|---|---|
{personReference} |
The internal ID or external reference of the person. |
{historicalFieldCategoryIdentifier} |
The identifier of the historical field category (see table below). |
Body properties
| Field | Type | Required | Writable | Description |
|---|---|---|---|---|
<reference>.id |
integer | Yes | Yes | Internal ID of the assigned resource (or use <reference>.externalReferences). |
<reference>.externalReferences |
object | No | Yes | External reference identifying the assigned resource, instead of its ID. |
originalFrom |
string | Yes | Yes | Current start date of the entry (YYYY-MM-DD). Must be on or after 1900-01-01. |
updatedFrom |
string | Yes | Yes | New start date of the entry (YYYY-MM-DD). Must be on or after 1900-01-01. |
Historical field categories
| Endpoint | Reference field | Referenced collection |
|---|---|---|
department-history |
department |
departments |
employer-history |
employer |
employers |
job-history |
job |
jobs |
job-category-history |
jobCategory |
job-categories |
sector-history |
sector |
sectors |
work-location-history |
workLocation |
work-locations |
External references
The endpoint resolves {personReference} through the externalReferences query parameter, and the reference field from the request body. See the external references page for details.
| Collection | Predefined | Custom |
|---|---|---|
people (query parameter) |
@badge-number, @employee-number |
Supported |
departments, employers, jobs, job-categories, sectors, work-locations (body) |
Not available | Supported |
Error responses
| Status | Condition |
|---|---|
400 |
Invalid external reference specification, or the referenced resource cannot be resolved |
400 |
Validation failed (missing reference field, originalFrom or updatedFrom, date before 1900-01-01) |
401 |
Missing or invalid access token, or insufficient scope |
404 |
Person with the given ID or external reference does not exist, or no entry exists for originalFrom |
Success response
200 OK. The response body is empty.
Examples
Move a department history entry
PUT
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people/112568/department-history
{
"department": {
"id": 825
},
"originalFrom": "2025-03-15",
"updatedFrom": "2025-04-01"
}Move a job history entry using external references
PUT
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people/EMP1234/job-history?externalReferences=(people,@employee-number)
{
"job": {
"externalReferences": {
"customJobCode": "JOB-14"
}
},
"originalFrom": "2025-01-01",
"updatedFrom": "2025-02-01"
}