Skip to main content
POST
Create org unit
Creates an active org unit and answers 201 with the WorkforceOrgUnit it became. Body: name (not blank), structureTypeId (an active structure type), optional parentUnitId (an active org unit outside every customer organization; omit for a new root), description and code. The code is stored upper case with every other run of characters replaced by _; a blank code, or one starting CP_ (capital partners are created in the Console), is 400. Requires org:manage and workforce:read at the platform scope. A missing structure type or parent, or a parent that is or sits under a customer organization, is 404; an archived type, an inactive parent, a placement the structure-type tier rules forbid, a placement more than 64 levels deep, or a code another org unit already uses is 409. Without an Idempotency-Key, repeating a create creates a second unit.

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

Body

application/json
name
string
required

The org unit name, stored exactly as sent.

structureTypeId
string
required

An active org structure type ID.

Minimum string length: 1
parentUnitId
string

The active parent org unit ID; omit for a new root.

Minimum string length: 1
description
string
code
string

Optional unique code, stored upper case with every other run of characters replaced by _. It must not be blank, already used by another org unit, or start with CP_ (capital partners are created in the Console).

Response

Success

data
object
required
meta
object
required