> ## 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 Assessment object > Assessment cycles, who participates, the grades a cycle captured, and how they reach a person's live record **Quick Summary:** An assessment is a cycle with **two independent tracks** — employees self-assess and managers assess — each with its own window, deadline and status. Grades are captured inside the cycle and only later **promoted** into the person's live skill record. Administer the cycle, read who participates and what they were graded, and pull the reports. Conducting an assessment — grading, and marking a track complete — is done in the product, not through the API. ## Attributes | Field | Type | Description | | -------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Opaque assessment id | | `title` / `description` | string | | | `status` | string \| null | Cycle lifecycle: `draft`, `active`, `completed`, `cancelled` | | `tracks.employee` / `tracks.manager` | object | `{ status, startedAt, endedAt, deadlineAt }` per track — the same lifecycle vocabulary, kept separate. A cycle can be closed for employees and open for managers | | `startedAt` / `endedAt` / `deadlineAt` | string \| null | Overall dates | | `managerGradesVisibleAt` | string \| null | When the employee may see their manager's grades: `immediately`, `after_employee_assessment`, `after_manager_assessment`, `after_assessment_ended` | | `allPeople` | boolean | Targets everyone rather than a scoped population | | `counts` | object | `assigned`, `completed`, `employeesAssigned`, `employeesCompleted`, `managersAssigned`, `managersCompleted` — over assessable people (those with a career that has proficiency and assessments enabled) | | `createdAt` / `updatedAt` | string \| null | | The detail read adds `scope`: `{ allPeople, businessUnitIds, divisionIds, countryIds, businessRegionIds, cityIds, siteIds, departmentIds, teamIds, shiftIds, peopleTypeIds }`. Assessment scoping supports nine of the eleven org dimensions — building and state are not part of it. ```json theme={null} { "id": "42", "title": "Q2 Skills Review", "description": "Annual proficiency check-in.", "status": "active", "tracks": { "employee": { "status": "active", "startedAt": "2026-03-01T00:00:00.000Z", "endedAt": null, "deadlineAt": "2026-03-31T00:00:00.000Z" }, "manager": { "status": "draft", "startedAt": null, "endedAt": null, "deadlineAt": "2026-04-15T00:00:00.000Z" } }, "startedAt": "2026-03-01T00:00:00.000Z", "endedAt": null, "deadlineAt": null, "managerGradesVisibleAt": "after_employee_assessment", "allPeople": false, "counts": { "assigned": 120, "completed": 0, "employeesAssigned": 118, "employeesCompleted": 60, "managersAssigned": 14, "managersCompleted": 0 }, "createdAt": "2026-02-20T09:00:00.000Z", "updatedAt": null } ``` ## Operations ### Cycles | Operation | Method and path | Requires scope | | ----------------------------------- | --------------------------------------- | ------------------- | | List assessments | `GET /api/v1/assessments` | `assessments:read` | | Get an assessment | `GET /api/v1/assessments/{id}` | `assessments:read` | | Create an assessment | `POST /api/v1/assessments` | `assessments:write` | | Update an assessment | `PATCH /api/v1/assessments/{id}` | `assessments:write` | | Start a track | `POST /api/v1/assessments/{id}/start` | `assessments:write` | | End a track | `POST /api/v1/assessments/{id}/end` | `assessments:write` | | Attach population selections | `POST /api/v1/assessments/{id}/scope` | `assessments:write` | | Detach population selections | `DELETE /api/v1/assessments/{id}/scope` | `assessments:write` | | Nudge participants | `POST /api/v1/assessments/{id}/nudge` | `assessments:write` | | Active counts for the acting person | `GET /api/v1/assessments/active-counts` | `assessments:read` | **Creating** takes `title`, `description`, `managerGradesVisibleAt`, the population — `allPeople: true`, or a `scope` of org dimension ids and optional `peopleTypeIds` — and the two deadlines (`employeeDeadlineAt`, `managerDeadlineAt`). A new cycle is `draft` on both tracks and its participants are enrolled immediately. **Updating** follows the cycle's rules: title, description, visibility and population only while **both** tracks are draft; a track's deadline only while that track is draft. Anything else is a [409](/api-docs/errors/conflict). **Start** and **end** take `{ "track": "employee" | "manager" }` (`suppressEmails: true` on start skips the start emails). Draft → active → completed, per track; the cycle becomes `active` when the first track starts and `completed` when both have ended — at which point manager grades held for `after_assessment_ended` are promoted into the live records. A track in the wrong state is a 409. A start refused for another reason — nobody would receive it, the self-assessment flow has not been configured, or the build has no step anyone can answer — is also a 409, and its `detail` names that reason. **Scope** attach/detach take the same nine id lists and apply only to a draft cycle that does not target everyone; attaching to an all-people cycle is a 409. **Nudge** takes `{ "target": "employee" | "manager" | "direct_reports" }` and answers `202` — reminders are queued and delivered asynchronously. `direct_reports` is relative to the acting person as a manager. ### Participation | Operation | Method and path | Requires scope | | ------------------------------ | ---------------------------------------------------------- | ------------------- | | List people in an assessment | `GET /api/v1/assessments/{id}/people` | `assessments:read` | | List exclusions | `GET /api/v1/assessments/{id}/exclusions` | `assessments:read` | | Get a person's participation | `GET /api/v1/assessments/{id}/people/{personId}` | `assessments:read` | | Exclude or re-include a person | `PUT /api/v1/assessments/{id}/people/{personId}/exclusion` | `assessments:write` | A participant is `{ person, managerId, status, tracks: { employee, manager }, completedAt, excludedFromAssessment, excludedFromDirectReports, includedAt }`, where each track carries `{ status, completedAt, completedById }` and progress is `to_do`, `in_progress` or `completed`. Person path slots accept an email or the opaque id. Exclusion has **two independent forms**: from the cycle entirely, or only from the manager's direct-report view. The body carries either flag or both; an omitted flag is left as is. ### Assessment grades (read-only) | Operation | Method and path | Requires scope | | --------------------------------- | ------------------------------------------------------- | ------------------ | | List a person's assessment grades | `GET /api/v1/assessments/{id}/people/{personId}/grades` | `assessments:read` | One row per career skill the person is assessed on: ```json theme={null} { "skill": { "id": "77", "name": "Forklift Operation" }, "section": { "id": "5", "name": "Safety" }, "career": "Warehouse Operator", "self": { "grade": { "id": "7", "grade": 3, "label": "Proficient" }, "yearsOfExperience": 3, "notes": null, "gradedAt": "2026-03-05T10:00:00.000Z", "promoted": false }, "manager": { "grade": null, "yearsOfExperience": null, "notes": null, "gradedAt": null, "promoted": false }, "managerGradesVisible": true, "benchmark": { "id": "9", "grade": 4, "label": "Advanced" }, "priorSelfGrade": { "id": "5", "grade": 2, "label": "Developing" }, "priorManagerGrade": null, "notApplicable": false, "focus": { "manager": false, "employee": true } } ``` Every grade and benchmark is a **resolved rung** (`id`, numeric `grade`, `label`) from the company's [grading scale](/api-docs/resources/grading-scale), never a bare integer. `promoted` tells you whether that side has been copied into the person's live [person skill](/api-docs/resources/person-skill) yet — a live read mid-cycle will not show assessment grades that have not been promoted. Notes live on the assessment grade and are not carried forward. **Blind assessment.** When the key acts as the assessed person, the `manager` block (and `priorManagerGrade`) is `null` and `managerGradesVisible` is `false` until the cycle's `managerGradesVisibleAt` rule is met. Every other reader sees both sides. ### Reports | Operation | Method and path | Requires scope | | ------------------------ | ------------------------------------------------------------- | ------------------ | | Assessment report | `GET /api/v1/assessments/{id}/report?track=employee\|manager` | `assessments:read` | | Completion report | `GET /api/v1/assessments/{id}/completion-report` | `assessments:read` | | Assessment skills matrix | `GET /api/v1/assessments/{id}/skills-matrix` | `assessments:read` | The report is per participant (`employee`) or per assessing manager (`manager`), with status, completion date, deadline and org context. The completion report is one row per manager × direct report with the manager-track progress and both exclusion flags. The skills matrix is people against skills with self, manager and benchmark rungs, within the acting person's span. ## Excluded Recording a self or manager assessment and completing a track are human acts in the product and are not exposed. The comment thread on a grade is dialogue, not a result. Live grades belong to the person-skill resource; skills to the skill resource; org dimension values to org structure; assessment-time skill flags to flags. ## Permissions Reads and cycle administration resolve against the acting person's assessment permissions (administration is global-administrator only in the app). Participant-level reads resolve against their visibility of people — admin identities see the company, a manager their span, any person themselves — and an out-of-span person is a [404](/api-docs/errors/not-found). ## Related errors * [not-found](/api-docs/errors/not-found) — the assessment or person is not in your company or span * [conflict](/api-docs/errors/conflict) — a state the cycle does not allow (edit after start, start twice, end a draft track, scope an all-people cycle, nothing to nudge) * [validation-error](/api-docs/errors/validation-error) — a missing title, a bad track or target, malformed dates