> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage division hierarchies

> Create and update tenant-owned organizational divisions without cross-tenant moves, hierarchy cycles, or sibling-name conflicts.

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

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    T[Tenant] --> R1[Sales]
    T --> R2[Operations]
    R1 --> C1[Enterprise]
    R1 --> C2[SMB]
```

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

## Create flow

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    A[Choose tenant] --> B[Choose parent or root]
    B --> C[Choose unique sibling name]
    C --> D[Choose order and cost center]
    D --> E[POST ?dryRun=true]
    E --> F{Valid?}
    F -- No --> G[Correct scope, name, parent, or order]
    F -- Yes --> H[POST without dryRun]
    H --> I[Persist real division ID]
```

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "Sales",
  "parentId": null,
  "order": 1,
  "costCenter": "CC-SALES"
}
```

## Create a child division

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "Enterprise",
  "parentId": "68920e08eeaea4f2301eecb3",
  "order": 1,
  "costCenter": "CC-SALES-ENT"
}
```

## Reparent safely

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    A[PATCH parentId] --> B{Parent in same tenant and scope?}
    B -- No --> X[INVALID_REFERENCE or TENANT_NOT_IN_SCOPE]
    B -- Yes --> C{Would create cycle?}
    C -- Yes --> Y[DIVISION_CYCLE]
    C -- No --> D{Sibling name unique?}
    D -- No --> Z[DIVISION_NAME_NOT_UNIQUE_ON_SAME_LEVEL]
    D -- Yes --> E[Apply parent and order]
```

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.