Skip to main content
POST
Create a reporting category
Creates an active reporting category with a unique key (a lowercase letter, then up to 63 lowercase letters, digits or _), a label and an optional description. Returns 201 with the category. A key already in use answers 409 ending (REPORTING_CATEGORY_KEY_EXISTS); a 101st category answers 413. 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

Body

application/json
key
string
required

A stable key: a lowercase letter, then up to 63 lowercase letters, digits or _.

label
string
required

The category's display label.

description
string

What the category covers.

Response

Success

data
object
required
meta
object
required