This article collects the recurring operational scenarios in organization-chart management via REST API: how to onboard an employee, move them, replace someone in a position, change a role, historize a change. For the data model and the basic concepts (position, assignment, direct boss, vacant position, id and cross-entity references) read first the REST - Personnel and organization data model article. For the full payload structure of each endpoint and the meaning of each field, refer to the linked per-entity articles.

In the examples below: payloads with id = 0 are creations and require the full set of fields exposed by the view; payloads with a valued id are updates and include only the fields you want to modify — the other fields in the view keep their previous value.

Onboarding a new employee into the organization chart

Typical onboarding sequence for an employee already present in the personnel registry.

1. Create the position the employee will occupy

Call the Positions write endpoint with id = 0. Set Positions_ParentID to the id of the direct boss's position (or null if it is a root position):

{
  "data": [
    {
      "id": 0,
      "Positions_Name": "",
      "Positions_ParentID": 47896,
      "Positions_KeyID": 25876528,
      "Positions_FunzioneID": 87945,
      "Positions_LocationID": 87942,
      "Positions_Inherits": "true",
      "Positions_AutoName": "true",
      "Positions_CustomerID": "ReportName-RoleName-DirectBossName"
    }
  ]
}

2. Assign the employee to the position just created

Call the Employee-Positions write endpoint with id = 0, the employee id in EmployeesPositionsHistory_Employee, the id of the newly created position in EmployeesPositionsHistory_PosizioneID, a past StartDate and EndDate = null:

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

Unassign an employee from a position

To remove an employee from a position, call the Employee-Positions write endpoint passing the id of the history row and setting an end date before today:

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

If the closed assignment was the only active one on the position, the position becomes vacant (see Data model): it keeps its id, its ParentID and its reports.

Move an employee together with the whole branch of their reports

When an employee changes direct boss and their reports must follow them in the new branch, it is enough to move their position under the new parent: the entire sub-tree is repositioned automatically.

Call the Positions write endpoint passing the id of the employee's position and the new Positions_ParentID (the id of the new direct boss's position):

{
  "data": [
    {
      "id": 1234,
      "Positions_ParentID": 47896
    }
  ]
}

All positions that reported to the moved position keep reporting to it, now placed under the new direct boss.

Move only the employee, leaving the reports where they were

When you want to move only the employee under a new direct boss and leave their reports where they are, you have to:

1. close the current assignment — the old position becomes vacant and keeps the reports;
2. create a new position under the new direct boss;
3. assign the employee to the new position.

1. Close the current assignment

See Unassign an employee

2. Create the new position under the new direct boss

Set Positions_ParentID to the id of the new boss's position:

{
  "data": [
    {
      "id": 0,
      "Positions_Name": "",
      "Positions_ParentID": 58793,
      "Positions_KeyID": 25876528,
      "Positions_FunzioneID": 87945,
      "Positions_LocationID": 87942,
      "Positions_Inherits": "true",
      "Positions_AutoName": "true",
      "Positions_CustomerID": "ReportName-RoleName-DirectBossName"
    }
  ]
}

3. Assign the employee to the new position

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

Change the role of a position

To change the role associated with a position, call the Positions write endpoint passing the id of the position and the new Positions_FunzioneID (the id of the new role, retrieved from the Roles lookup):

{
  "data": [
    {
      "id": 1234,
      "Positions_FunzioneID": 58964
    }
  ]
}

If the position is in automatic-name mode, the name is updated accordingly after the write.

Historize a change (boss or role)

The change scenarios described above modify the position "in line": the employee keeps occupying the same position and no new row is generated in the assignment history. If you want instead to historize the change — that is, to have in the history a closed row with the old scenario and a new row with the new one — apply this three-step pattern:

1. close the current assignment;
2. modify the position: change Positions_ParentID for a direct-boss change, or Positions_FunzioneID for a role change;
3. re-assign the same employee to the same position with a new row (id = 0, new StartDate).

The pattern is identical for both cases: only the field changed at step 2 differs. The examples for steps 2 and 3 follow (for step 1 see the Unassign an employee section above).

Step 1 —  close the current assignment

See Unassign an employee

Step 2.a — modify the position (direct-boss change variant)

{
  "data": [
    {
      "id": 1234,
      "Positions_ParentID": 47896
    }
  ]
}

Step 2.b — modify the position (role change variant)

{
  "data": [
    {
      "id": 1234,
      "Positions_FunzioneID": 58964
    }
  ]
}

Step 3 — re-assign the employee to the same position

Call the Employee-Positions write endpoint with id = 0 and a new StartDate; EmployeesPositionsHistory_Employee and EmployeesPositionsHistory_PosizioneID stay the same as in the previous period:

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

Permissions

The scenarios described combine writes on the Positions and Employee-Positions history entities, and reads on the lookups to retrieve the ids to insert in the payloads. The user authenticating the integration must have, on their account, the permissions required on all the involved entities. Permissions are assigned to the individual user, not to a profile.

For the detailed permissions required by each endpoint, refer to the Permissions sections of the per-entity articles.

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 - Employee-position assignments via API