Skip to main content
Quick Summary: Org structure is two unrelated things. Eleven flat dimensions — businessUnits, divisions, businessRegions, countries, states, cities, sites, buildings, departments, teams, shifts — say where someone sits; the manager hierarchy says who they report to. They share nothing, and the dimensions have no parent-child structure between them.

​
Dimension values

Every dimension behaves identically. A value is { id, name, isActive }:
  • GET /api/v1/org/dimensions — the eleven keys.
  • GET /api/v1/org/{dimension} — every value, deactivated ones included.
  • POST /api/v1/org/{dimension} — create (name only; no ordering exists).
  • PATCH /api/v1/org/{dimension}/{id} — rename, or isActive: false to deactivate reversibly.
  • DELETE /api/v1/org/{dimension}/{id} — remove the value outright. When people hold it, the delete refuses with a 409 carrying the dependency counts (assignedPeople, personRecordReferences); retry with ?confirm=true to remove the memberships (and clear the legacy person-record column) and delete anyway. A value referenced by records outside this API — assessments, surveys, qual cards, saved views, or another org value — cannot be deleted even with confirm; deactivate it instead.
  • GET /api/v1/org/{dimension}/{id}/usage — how many people hold the value, before deactivating or deleting it.
  • GET /api/v1/org/{dimension}/{id}/people — everyone holding the value.

​
A person’s placement

Placement is many-to-many — someone can belong to two sites or three teams. It lives on the Person resource: GET|POST|DELETE /api/v1/people/{id}/org-schema (additive attach / explicit detach) and PUT /api/v1/people/{id}/org-schema/{dimension} to replace one dimension exactly.
One representation is published. Internally five org facts also exist in a second, legacy form on the person record (single-value department and business-region columns, free-text city/state/country strings). The API reads and writes the membership form only; the usage read reports legacy-column references for departments and businessRegions so any drift is visible.

​
Manager hierarchy

  • GET /api/v1/org/manager-tree — the company’s reporting hierarchy as flat parent-pointer rows ordered by depth (roots at level 0), company-scoped, paginated.
  • GET /api/v1/people/{id}/span-of-control — one person’s subtree, subject included at level 0.
Setting a person’s manager is PATCH /api/v1/people/{id}/manager on the Person resource.