Skip to main content
POST
Create position
Creates an OPEN position in an org unit and answers 201 with the WorkforcePosition it became. Body: orgUnitId, title (not blank), optional description, reportsToPositionId and agentAssignable. Requires org:manage and workforce:read at that org unit, as in the Console. A missing org unit, one that is or sits under a customer organization, and one outside the caller’s workforce:read all answer the same 404; 403 means the caller can read the unit but lacks org:manage there. An unknown or unreadable reporting position is 404. An inactive org unit, or a reporting chain that would loop, pass through a missing or inactive position or an inactive org unit, or exceed 100 positions, is 409. Without an Idempotency-Key, repeating a create creates a second position.

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
orgUnitId
string
required

The org unit the position belongs to (its home).

Minimum string length: 1
title
string
required
description
string
reportsToPositionId
string

The position this one reports to.

Minimum string length: 1
agentAssignable
boolean

Response

Success

data
object
required
meta
object
required