Skip to main content
Quick Summary: A career is not a flat record — it is a complete competency model. The object below is the library entry; GET /api/v1/careers/{id}/definition returns the whole model in one call.

​
Attributes

​
The definition

The full definition (/careers/{id}/definition) additionally carries settings, the company gradingScale, and complete levels, sections, skillGroups, skills and learnings arrays. Two things to know:
  • Benchmarks are always resolved rungs — { "id": "46", "grade": 1, "label": "Basic awareness..." }, never a bare integer. The id references the company grading scale.
  • Each skill carries its full configuration: section, groups, position, career-wide benchmark, its stored requirement configuration, evidence rules, expiry, and per-level activation for every level of the career.

​
The requirement object

Each career skill carries a requirement object — the stored configuration, never a resolved boolean:
Whether a skill is actually Required for a person is resolved against that person’s assignment date, so it belongs to person-scoped reads — a career is a company-level object, and no single boolean here can be true for everyone. isRequired reflects the stored flag with null resolved: only an explicit false turns a requirement off. scope is all (binds everyone holding the career) or going_forward (applies only to people assigned on or after effectiveFrom).

​
How skills reach assignees

A career’s skills are delivered to a person when they are assigned at a level, and only the skills active on that level are delivered. Attaching a skill to a career that already has levels activates it on every existing level, and adding a level activates every existing skill on it — whether the skill sits directly on the career, in a section or in a skill group. PATCH /careers/{id}/skills/{careerSkillId}/levels/{levelId} adjusts a skill’s per-level benchmark, or switches it off for a level. The isCompleted/isApproved flags play no part in this.

​
Editing sections, levels and skill groups

PATCH /careers/{id}/sections/{careerSectionId} is partial: name, description and minimumRequiredSkills. Name and description belong to the library section the career attaches, so a rename shows on every career that uses it. The three reorder operations (/levels/reorder, /sections/reorder, /skill-groups/reorder) take { "ids": [...] } — every id of the collection in the desired order — the same field every reorder in this API takes. The resource-named fields they shipped with (levelIds, sectionIds, skillGroupIds) remain accepted as deprecated aliases.

​
Guarded deletes

Deleting a career (or one of its levels) that would have consequences refuses with a 409 conflict reporting exactly what stands in the way; retrying with ?confirm=true proceeds deliberately.