Skip to main content
PATCH
Update position assignment
Changes an assignment’s assignmentKind, startDate or endDate, with a non-blank audited reason; endDate: null reopens it, and omitted fields keep their value. Returns the updated assignment row. Without an Idempotency-Key, a repeat writes and audits again. 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

positionAssignmentId
string
required

The assignment to change.

Minimum string length: 1

Body

application/json
reason
string
required

Why the assignment changes; it is audited.

assignmentKind
enum<string>

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

Available options:
PRIMARY,
SECONDARY
startDate
integer

The new start, epoch milliseconds.

Required range: 0 <= x <= 9007199254740991
endDate
integer | null

The new end, epoch milliseconds, or null to reopen the assignment.

Required range: 0 <= x <= 9007199254740991

Response

Success

data
object
required
meta
object
required