This article describes how to manage employee-position assignments (creation, update, closure) through the Altamira REST API. For the general context and the organization-chart model refer to the REST - Managing personnel and organization chart via API article.

Reference entity

Employee-position assignments are managed through the Employee-Positions history entity: the same entity represents both the active assignments (with end date not set) and the historical ones (closed). Working on the history entity is the correct mode both for reads and for all write operations, including closures.

Endpoints to prepare

• Create an Endpoint/View to extract data of the existing employee-position assignments (use the Employee-Positions history entity).
• Create an Endpoint/View to create/update/deactivate employee-position assignments (include the Employee field as a list-type field and use the Employee-Positions history entity).

The same write endpoint is used both to create a new assignment and to close/deactivate it.

Create an active assignment

The write endpoint accepts a POST call with a payload in the following shape:

{
  "data": [
    {
      "id": 0,
      "EmployeesPositionsHistory_CustomerID": "DirectBossMain1",
      "EmployeesPositionsHistory_StartDate": "2026-03-01T00:00:00Z",
      "EmployeesPositionsHistory_EndDate": null,
      "EmployeesPositionsHistory_OrganigrammaID": "25876528",
      "EmployeesPositionsHistory_PosizioneID": "27160176",
      "EmployeesPositionsHistory_Employee": "27160150"
    }
  ]
}

Meaning of the fields

• id — 0 to create a new assignment, the history row identifier to update or close.
• EmployeesPositionsHistory_CustomerID — unique identifier of the assignment in the customer system. Useful to reconcile Altamira rows with the external data set.
• EmployeesPositionsHistory_StartDate — start date of the assignment. Use a date before today for an active assignment.
• EmployeesPositionsHistory_EndDate — end date of the assignment. Use null for an active assignment.
• EmployeesPositionsHistory_OrganigrammaID — ID of the organization chart the linked position belongs to.
• EmployeesPositionsHistory_PosizioneID — ID of the position the employee is assigned to.
• EmployeesPositionsHistory_Employee — ID of the employee to assign. The Employee field must be present in the view as a list-type field.

Rules on dates and state

• StartDate in the past + EndDate = null → active assignment.
• EndDate set → closed assignment: the employee is no longer assigned to that position starting from the given date.

Close/deactivate an assignment

To deactivate (close) an employee-position assignment, use the same write endpoint, setting the id field to the history-row identifier and putting an end date before today:

{
  "data": [
    {
      "id": 27160260,
      "EmployeesPositionsHistory_EndDate": "2026-04-01T00:00:00Z"
    }
  ]
}

You do not need to send the other fields: their existing values are preserved.

Read

The read endpoint replies to a GET call and returns the history rows (active and closed) contained in the view. Add to the view the fields needed for the use case and apply any client-side filters (by employee, by position, by date range) as described in the REST - Read call with filter example article.

Operational notes

• Dates must be in the "2026-04-02T00:00:00Z" format.
• The fields shown in the examples are the minimum set required to manage assignments correctly: names and structure must be respected. Additional fields can be added to the views to meet customer needs.
• The Employee field must be included in the view as a list-type field: it is the reference the API uses to link the assignment to the employee.
• Before creating an assignment, make sure that both the employee and the target position exist (see REST - Employee personal data via API and REST - Organization chart and positions via API).

Permissions

• Read on the Employee-Positions history entity for GET calls.
• Write on the Employee-Positions history entity for create, update and close.
• Read on the Employees and Positions entities, to retrieve the IDs to insert in the payloads.

Related articles

• REST - Managing personnel and organization chart via API
• REST - Personnel and organization data model
• REST - Employee personal data via API
• REST - Organization chart and positions via API
• REST - Common operational scenarios for the organization chart via API
• REST - Read call with filter example
• REST - Write call example