> ## Documentation Index
> Fetch the complete documentation index at: https://help.skillsdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Career object

> A structured competency model: levels, sections, skill groups, skills and learnings

<Info>
  **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.
</Info>

## Attributes

| Field                     | Type                  | Description                                                |
| ------------------------- | --------------------- | ---------------------------------------------------------- |
| `id`                      | string                | Opaque career id                                           |
| `name`                    | string                | Career name                                                |
| `description`             | string \| null        | Description                                                |
| `icon`                    | string \| null        | Icon identifier                                            |
| `careerType`              | object \| null        | Reference `{ id, name }` to the family it is grouped under |
| `levelCount`              | integer               | Number of levels defined                                   |
| `isCompleted`             | boolean               | Marked completed                                           |
| `isApproved`              | boolean               | Marked approved                                            |
| `createdAt` / `updatedAt` | string (ISO 8601 UTC) | Timestamps; `updatedAt` may be `null`                      |

```json theme={null}
{
  "id": "18",
  "name": "Maintenance Technician",
  "description": "Keeps the line running.",
  "icon": "wrench",
  "careerType": { "id": "3", "name": "Job Role" },
  "levelCount": 3,
  "isCompleted": false,
  "isApproved": true,
  "createdAt": "2026-01-12T08:30:00.000Z",
  "updatedAt": "2026-03-02T14:00:00.000Z"
}
```

## 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](/api-docs/resources/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:

```json theme={null}
{
  "isRequired": true,
  "scope": "going_forward",
  "effectiveFrom": "2026-03-01T00:00:00.000Z",
  "setBy": { "id": "88", "name": "Dana Reviewer" }
}
```

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`).

## Guarded deletes

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