Quick Summary: One scale per company. Every benchmark on every career, and every achieved grade, references a rung of this scale by id. A new company starts with an empty scale — add rungs before grading anything. Once any grade in the company references the scale, a rung’s numeric grade is locked and rungs can no longer be removed; labels, descriptions and the active flag stay editable.
Attributes (per rung)
Writing the scale
POST takes { "grade": 3, "label": "Proficient", "description": "..." } — one rung per call, the grade unique within the company. The rung is active and immediately usable as a gradeId on self-, manager- and benchmark grades. A grade that already exists is a 409: update that rung instead.
PATCH is partial: any of grade, label, description, isActive. Once the scale is in use, changing grade is a 409. DELETE answers 204 for a rung nothing references and a 409 once the scale is in use — deactivate the rung instead.
Why the API never returns a bare benchmark integer
A rung carries two integers — its id and its grade value — and they routinely differ. A barebenchmark: 4 could denote a rung whose actual grade is 2, and an integrator would compute gaps against the wrong number silently. The API therefore always returns the resolved rung: { id, grade, label }.