Manage division hierarchies

Divisions form a hierarchy inside one tenant. A division has a name, optional parent, sibling display order, optional cost center, and server-assigned timestamps.

Hierarchy model

parentId: null creates or moves a division to the tenant root.

Create flow

If X-Tenant-ID is omitted, the create operation may infer the tenant from parentId or an unambiguous key scope. Send the header when more than one tenant is possible.

Create a root division

{
  "name": "Sales",
  "parentId": null,
  "order": 1,
  "costCenter": "CC-SALES"
}

Create a child division

{
  "name": "Enterprise",
  "parentId": "68920e08eeaea4f2301eecb3",
  "order": 1,
  "costCenter": "CC-SALES-ENT"
}

Reparent safely

A division cannot be moved to another tenant through the public update endpoint.

Patch behavior

Omit properties that should remain unchanged.
Set parentId: null to move to the root.
Set nullable costCenter: null to clear the cost center.
Use dry run before hierarchy changes.
Persist the returned state after the real patch.

Ordering

order is a numeric display order among sibling divisions. The updated provider schema uses the OpenAPI type number and no longer applies the previous integer-only multipleOf: 1 constraint. The create operation documents a server default after the last sibling when the value is omitted. The public contract does not guarantee that sibling order values are unique or automatically renumbered; read the resulting hierarchy and use the returned values.

Public limitations

The public v1 contract does not expose division deletion. It also does not define a maximum hierarchy depth or promise automatic sibling renumbering after every order change. Coordinate removal and employee reassignment through the applicable business process, keep hierarchies reasonably bounded, and read the resulting order values instead of assuming them.

Get Started

Architecture & Concepts

Integration Guides

Operations

Hierarchy model

Create flow

Create a root division

Create a child division

Reparent safely

Patch behavior

Ordering

Public limitations

​Hierarchy model

​Create flow

​Create a root division

​Create a child division

​Reparent safely

​Patch behavior

​Ordering

​Public limitations

Hierarchy model

Create flow

Create a root division

Create a child division

Reparent safely

Patch behavior

Ordering

Public limitations