Skip to main content
POST
Confirm a direct staffing assignment
Staffs one active Employee or Contractor worker on the project from startsAt, with optional endsAt, deliveryRole and allocationPercent (a whole percent, 1 to 100). Going over the worker’s capacity needs overAllocationReason, which is kept on the row. Returns 201 with the new assignment, attributed to the calling External App or key. Needs workforce:manage at the platform scope (a grant that covers only some org units receives 403) and projects:read at the project’s home: a project that is missing, has no home, or that you cannot read answers 404. Because the answer is a staffing read, the credential’s scopes must include workforce:read and projects:read as well as workforce:manage (otherwise 403 naming the missing one, and nothing changes). A refusal is 400, 404, 409 or 413 and its message ends with the Console’s code in parentheses. Rows never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept. Send an Idempotency-Key to make a retry safe; see Project staffing replay.

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

projectId
string
required

The project's ID (id from GET /api/v2/projects/list).

Minimum string length: 1

Body

application/json
workerId
string
required

An active Employee or Contractor worker seat linked to a person.

Minimum string length: 1
allocationPercent
number
required

The worker's allocation: whole percent of the worker's capacity, 1 through 100.

startsAt
integer
required

When the assignment starts, epoch milliseconds.

Required range: 0 <= x <= 9007199254740991
deliveryRole
string

The worker's delivery role on the project.

endsAt
integer

When the assignment ends, epoch milliseconds.

Required range: 0 <= x <= 9007199254740991
overAllocationReason
string

Required when the worker would exceed 100% (409 OVER_ALLOCATION_REQUIRES_REASON).

Response

Success

data
object
required
meta
object
required