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
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.
Operations
Cycles
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.
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
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)
One row per career skill the person is assessed on:
id, numeric grade, label) from the company’s grading scale, never a bare integer. promoted tells you whether that side has been copied into the person’s live 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
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.Related errors
- not-found — the assessment or person is not in your company or span
- 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 — a missing title, a bad track or target, malformed dates