Skip to main content
POST
Move org unit
Moves an org unit and its whole subtree under an active new parent, or to the root with newParentUnitId: null, and answers the moved WorkforceOrgUnit. Requires org:manage and workforce:read at the platform scope. A missing unit or parent, or one that is or sits under a customer organization, is 404, so a unit never moves into or out of a customer organization. An inactive parent, a placement the structure-type tier rules forbid, a placement more than 64 levels deep, moving a unit under itself or a descendant, moving a capital partner, or moving a unit with 500 or more descendants (move its subtrees first) is 409.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

orgUnitId
string
required

The org unit to move.

Minimum string length: 1

Body

application/json
newParentUnitId
string | null
required

The active new parent org unit ID, or null to make the unit a root.

Minimum string length: 1

Response

Success

data
object
required
meta
object
required