Skip to main content
POST
Create organizational unit

Authorizations

X-API-Key
string
header
required

Owner-typed API key (ORGANIZATION, PERSON, VALUE_UNIT). Manage org-scoped lifecycle with /v1/public-api-keys; cross-org governance is restricted to /v1/sys/public-api-keys.

Body

application/json

Create payload. Resolve typeId first via GET /v1/public/organizational-units/types and headId/deputyHeadId via GET /v1/public/people when assigning organizational unit roles.

name
string
required
Maximum string length: 150
Pattern: \S
typeId
string
required

Organizational unit type tag id. Resolve via GET /v1/public/tags/organizational-unit-types.

Pattern: \S
Example:

"77f8a9e1-6131-4f74-9477-c3dd1f98d352"

parentId
string
required

Parent organizational unit id inside the authenticated organization.

Pattern: \S
Example:

"a5ec8a9e-b6a9-4230-9ce9-8db4bb40f6ff"

description
string

Optional organizational unit description.

externalId
string

Optional external identifier used by upstream systems for stable integration mapping.

Maximum string length: 255
Example:

"hris-ou-1001"

headId
string

Optional organizational unit head person id inside the authenticated organization. Resolve via GET /v1/public/people.

Example:

"2f6db7d4-6e6c-4d4f-90f2-cbaac8441f7b"

deputyHeadId
string

Optional organizational unit deputy head person id inside the authenticated organization. Resolve via GET /v1/public/people.

Example:

"7b4f1a91-57cd-4a5e-b1f8-16b5705de95b"

tags
string[]

Optional ad-hoc custom tags for the organizational unit. Omit to keep it untagged.

Maximum array length: 5
Example:

Response

Organizational unit created

id
string
name
string
description
string
externalId
string
parentId
string
parentName
string
typeId
string
typeName
string
headId
string
headName
string
deputyHeadId
string
deputyHeadName
string
tags
object[]
valueUnits
object[]
clients
object[]
hasChildren
boolean