Assign a historical field
Assigns a person to a department, employer, job, job category, sector or work location from a given date.
Tip
Check the Swagger page for more technical information on the endpoints.
Endpoint details
POST
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
Each endpoint accepts one reference field, named after the historical field it manages.
| 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. |
from |
string | Yes | Yes | Date from which the assignment applies (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 or from, from 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 |
Success response
201 Created. The response body is empty.
Examples
Assign a department by internal ID
POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people/112568/department-history
{
"department": {
"id": 825
},
"from": "2025-03-15"
}Assign a work location using external references
POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people/123456/work-location-history?externalReferences=(people,@badge-number)
{
"workLocation": {
"externalReferences": {
"customWorkLocationCode": "WL-HOME"
}
},
"from": "2025-04-01"
}