Skip to main content
POST
Create position assignment
Seats a worker in a position from startDate (until endDate, when given) as a PRIMARY or SECONDARY assignment, with a non-blank reason recorded in the audit log with the calling key or app. Returns 201 with the assignment row, in the shape List assignment history returns. Seating an agent gives it the agent_worker role, as the Console does. Without an Idempotency-Key, repeating a create records a second assignment, or is refused as an overlapping primary. Requires org:manage and workforce:read at the platform scope, as the Console’s people page does; a grant that covers only some org units is 403. The credential’s scopes must include workforce:read as well as org:manage, because the success returns the assignment; otherwise 403 naming workforce:read, and nothing changes. A worker with any assignment that has not ended in a position in or under a customer organization, or without an org unit, every other seat of that worker’s person, a position homed in or under a customer organization or without an org unit, an assignment naming either, and a missing ID are 404, exactly as a missing row. Refusals end with the Console’s code in parentheses and write nothing: 400 for a blank reason or an end not after the start, 409 for an inactive worker, position or org unit, an agent in a position that is not agent-assignable, or an overlapping or ambiguous primary, and 413 past 500 assignments. The Console’s rule that an agent cannot manage a human worker is refused as 500, with nothing written. Send an Idempotency-Key to make a retry safe: a same-key retry within 24 hours returns the recorded result only while you keep that authority and can still see every assignment it names; otherwise 409 idempotency_result_unavailable. If an outcome is unknown, repeat with the same key or read the worker’s rows with List assignment history.

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 the worker fills.

Minimum string length: 1

Body

application/json
workerId
string
required

The worker to seat.

Minimum string length: 1
assignmentKind
enum<string>
required

PRIMARY (at most one effective at a time per worker) or SECONDARY.

Available options:
PRIMARY,
SECONDARY
startDate
integer
required

When the assignment starts, epoch milliseconds.

Required range: 0 <= x <= 9007199254740991
reason
string
required

Why the assignment changes; it is audited.

endDate
integer

When the assignment ends; omit for an open assignment, epoch milliseconds.

Required range: 0 <= x <= 9007199254740991

Response

Success

data
object
required
meta
object
required