Quick Summary: A career is not a flat record — it is a complete competency model of levels, sections, skill groups, skills and learnings. This group is the model itself. Who holds a career is a career assignment in Team Data.
The resources
Read the whole model in one call
The career object is the library entry.GET /api/v1/careers/{id}/definition returns the entire competency model — levels, sections, groups, skills and learnings — in a single response, which is what an integration rendering a career should use rather than walking the parts.
One scale, company-wide
There is exactly one grading scale per company. Every benchmark on every career and every achieved grade references a rung of that scale by id. Grades and benchmarks are always returned as resolved rungs ({ id, grade, label }), never as bare integers — an integer alone does not rank meaningfully.
The scale is writable with careers:write: add, update and remove rungs. A new company starts with an empty scale, so 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 (409) — labels, descriptions and the active flag stay editable, so deactivate a rung instead of deleting it. See The Grading Scale.
Deleting is guarded
A career type cannot be deleted while careers still use it. This is the pattern across the library resources: definitions that other records point at refuse deletion rather than orphan those records.Activity
GET /api/v1/careers/{id}/activity is the fullest activity feed on the API — roughly 40 event types covering lifecycle, settings, skills, sections, levels, groups, learnings, assignments, labels and flags. It accepts from/to date filters, which makes it the feed a poller should watch.