Skip to main content
PATCH
Update a reporting category
Replaces a reporting category’s label, description (omit it to clear it) and retired flag at the expectedRevision you last read; the key never changes. Returns 200 with the category. A categoryId that is not a reporting category answers 404; a stale revision answers 409 ending (REPORTING_CATEGORY_CHANGED). Needs workforce:manage at the platform scope (Console parity): a grant that covers only some org units receives 403. The credential’s scopes must include workforce:read as well as workforce:manage, because the success returns the written row; otherwise 403 naming workforce:read, and nothing changes. The command is the Console’s own, so its validation, revision and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console’s code in parentheses. The result never names who created or updated the row. Send an Idempotency-Key to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include workforce:read and you still hold workforce:manage at the platform scope; otherwise 409 idempotency_result_unavailable, and the change never runs twice.

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

reportingCategoryId
string
required

The reporting category's ID (from GET /api/v2/workforce/listReportingCategories).

Minimum string length: 1

Body

application/json
expectedRevision
integer
required

The category's revision you last read; a stale value is 409 REPORTING_CATEGORY_CHANGED.

Required range: x >= 0
label
string
required

The category's display label.

retired
boolean
required

Whether the category is retired (hidden from new choices).

description
string

What the category covers; omit to clear it.

Response

Success

data
object
required
meta
object
required