Skip to main content
POST
Set position reporting
Sets the position a position reports to, or clears it with reportsToPositionId: null, and answers the WorkforcePosition. A non-blank reason is required and recorded in the audit log with the calling key or app. Requires org:manage and workforce:read at the platform scope. An unknown position, or one in or under a customer organization, is 404. An active position whose org unit is inactive, or an edge whose chain would loop, pass through a missing or inactive position or an inactive org unit, or exceed 100 positions, 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

positionId
string
required

The position whose reporting edge changes.

Minimum string length: 1

Body

application/json
reportsToPositionId
string | null
required

The position it reports to, or null to clear the edge.

Minimum string length: 1
reason
string
required

Why the edge changes; recorded in the audit log.

Response

Success

data
object
required
meta
object
required