Quick Summary: A person skill is a skill on a person’s profile. It carries the person’s self grade and the manager’s grade (each with years of experience), a resolved benchmark, the not-applicable and focus flags, and its origin — attached directly, derived from one or more careers, or both. A grade is a value on the record; the record itself is not a score. Every grade and benchmark is a resolved rung (
{ id, grade, label }), never a bare integer.Attributes
The benchmark rule is the app’s, written down: most specific wins — the manager benchmark, then the assignment level’s benchmark (whenever the assignment has a level, even if that level sets none), then the career’s benchmark. Across several careers the highest career-derived effective value is published as
benchmark.effective; the contributing values are all present so a caller can see which one won.
Operations
A person’s skills
personId is an email or an opaque id. The list returns every skill on the profile — attached directly or derived from a career — with the full object above. The population read is one operation over the app’s three reads: scope=company needs an administrator-level acting person; scope=team and scope=org read the team or organisation branch of the manager named by subject, who must be the acting person or within their span. Rows are one per person per skill (per career when graded through one) and are filterable by skillName, skillId, firstName, lastName.
Grading
Grades take
{ "gradeId": "3", "yearsOfExperience": 4, "comment": "…" }; gradeId must be a rung of the company grading scale (a field-level validation error otherwise). Only the person may set their self grade; the manager grade needs the acting person to manage the subject or to be an administrator.
Grade across a career takes { "grades": [{ "skillId", "managerGradeId"?, "managerYearsOfExperience"?, "selfGradeId"?, "selfYearsOfExperience"? }] } and applies to skills the career requires for that person; any other skill is 422 unprocessable.
Grading attaches the skill directly as well, as the app does: after a grade, origin.direct is true even for a skill that arrived through a career, and the career derivation is kept alongside it.
Benchmark takes { "gradeId": "4" } or { "gradeId": null } to clear — never a zero. Not applicable takes { "notApplicable": true } and clears the person’s manager grade: this is not a display flag, it discards data. Focus takes { "employee": true } (the person only) and/or { "manager": true }; clearing the manager flag also clears the employee flag, as in the app.
Remove must say which attachment goes: attachment=direct (the default) drops the skill added in its own right — a 404 when the skill is only career-derived; attachment=career&careerId=31 clears the grade held through one career — the derivation itself stays for as long as the career requires the skill; attachment=all does both. To take a career-required skill off a profile, remove the career assignment (see Career) or the skill from the career.
Grade reporting
Statistics answers
{ attachedSkills, benchmarksMet, variances, skillGaps }. Scorecard is the app’s named surface and is assessment-scoped: assessmentId names the cycle the grades are rolled up within (required; a person who is not a participant of that cycle is a 404). The roll-up is per career assignment. Note that the scorecard’s totalBenchmarkMet is measured against the career benchmark only, as in the app — it ignores the level and manager benchmarks that the person skill’s benchmark.effective resolves. Trends returns per-period averages of the self and manager grades of the people on the career.
Permissions
Any person who can see a person in the app can read their skills, statistics and scorecard here. Grading follows the app: a person grades themself; their manager (or an administrator) sets the manager grade, benchmark, not-applicable and manager-focus flags and removes skills. A key acting as someone outside those relationships receives insufficient-permissions or, for a person outside its span, not-found.Excluded
What a career requires — benchmarks, per-level activation and required status — belongs to Career. The skill itself belongs to Skill. Training records belong to Training; grades set through an assessment cycle belong to Assessment and are readable here once set. Skill flags on a person belong to Flag. CSV grade import is an in-app path.Related errors
- not-found — the person is not in your company or outside your span; the skill is not on their profile; the attachment asked for does not exist
- validation-error — an unknown rung, a missing
subjectorcareerId, an unknownscopeorattachment - unprocessable — grading a skill that is not part of the career
- insufficient-permissions — setting another person’s self grade or employee focus; a non-administrator asking for the company-wide population