This article describes how to read, create, update and delete positions in the organization chart through the Altamira REST API, along with the lookup tables needed to populate the payloads (Organization charts, Roles, Locations). For the general context refer to the REST - Managing personnel and organization chart via API article.

Organization-chart model

The organization-chart structure is managed through the Positions entity, whose elements are linked hierarchically through the ParentID field: each position points to the position above. The positions at the top of the tree (root) have ParentID = null. The chart is managed to support the linear Report — Direct boss — Boss relationship without Organizational Units.

Endpoints to prepare

Positions

• Create an Endpoint/View to extract position data.
• Create an Endpoint/View to create/update positions.

Lookup tables

• Create an Endpoint/View to extract data from the Organization charts lookup.
• Create an Endpoint/View to extract data from the Roles lookup.
• Create an Endpoint/View to extract data from the Locations lookup.

The three lookup views return the IDs that must then be set in the Positions_KeyID, Positions_FunzioneID and Positions_LocationID fields of the position write payloads.

Write — create a position

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

Example — root position

{
  "data": [
    {
      "id": 0,
      "Positions_Name": "LastName FirstName - Role",
      "Positions_ParentID": null,
      "Positions_KeyID": 12345,
      "Positions_FunzioneID": 56897,
      "Positions_LocationID": 87942,
      "Positions_Inherits": "true",
      "Positions_AutoName": "false",
      "Positions_CustomerID": "DirectBoss_0001"
    }
  ]
}

Example — child position

{
  "data": [
    {
      "id": 0,
      "Positions_Name": "LastName FirstName - Role",
      "Positions_ParentID": 88888,
      "Positions_KeyID": 12345,
      "Positions_FunzioneID": 87945,
      "Positions_LocationID": 87942,
      "Positions_Inherits": "true",
      "Positions_AutoName": "false",
      "Positions_CustomerID": "Report_0001"
    }
  ]
}

Meaning of the fields

• id — 0 to create a new position, the position identifier to update.
• Positions_Name — position name (see Position name behavior below).
• Positions_ParentID — identifier of the position above. null for root positions, the ones at the top of the organization-chart structure.
• Positions_KeyID — ID of the Organization chart the position belongs to.
• Positions_FunzioneID — ID of the Role associated with the position.
• Positions_LocationID — ID of the Location associated with the position.
• Positions_Inherits — inheritance flag.
• Positions_AutoName — mode used to build the position name (see below).
• Positions_CustomerID — unique identifier of the position in the customer system. Useful to reconcile Altamira positions with the external data set.

Position name behavior (Positions_AutoName)

• "true" → the position name must be built manually in the Positions_Name field.
• "false" → the position name is built automatically with the syntax LastName FirstName - Role.

Update a position

To update an existing position run a POST call on the same endpoint passing the position id and the fields you want to modify.

Delete a position

Use the write endpoint with the DELETE method.

Constraints

• You cannot delete positions that contain active employees.
• You cannot delete positions that have child elements in the organization chart.

Before deletion, the integration must therefore deactivate/move the associated employees and remove or re-parent the child positions.

Read

• Read positions — returns the positions contained in the view. Add to the view the fields needed for the use case.
• Read full organization chart — returns the tree structure of an organization chart's positions, useful to rebuild the hierarchy in the external system.

Operational notes

• Dates must be in the "2026-04-02T00:00:00Z" format.
• The fields shown in the examples are the minimum set for writing positions correctly: names and structure must be respected. Additional fields can be added to the views to meet customer needs.
• To build the hierarchy correctly, create the upper-level positions first and then the child ones, setting Positions_ParentID with the identifier returned by the parent's creation call.

Permissions

• Read on the Positions entity for GET calls.
• Write on the Positions entity for create and update.
• Delete on the Positions entity for DELETE calls.
• Read on the Organization charts, Roles and Locations lookups, 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 - Employee-position assignments via API
• REST - Common operational scenarios for the organization chart via API
• REST - Read call example
• REST - Write call example