Skip to main content
Quick Summary: There are TWO flag systems sharing no tables: people flags (/api/v1/people-flags) tag a person; skill flags (/api/v1/skill-flags) tag a person at a career, section, skill-group or skill scope. A flag is the company-configured type; a flag assignment is a person carrying one.

​
Attributes (both systems)

Disabling hides existing assignments — it does not merely block new ones. Every assignment of a disabled flag disappears from the assignment reads, and for skill flags also from trainer counts, metrics and the training approver pool: someone carrying a trainer-designating flag stops counting as a trainer the moment it is disabled. No rows are deleted — re-enabling restores everything. An integrator reconciling assignments will otherwise see rows vanish with no corresponding delete.

​
People flags

CRUD plus POST /{id}/enable, POST /{id}/disable, POST /reorder, GET /{id}/dependencies, and a guarded DELETE /{id} (409 with the holder count; ?confirm=true proceeds). Assignments: GET /people-flags/{id}/people, and per person GET|POST|DELETE /people/{id}/people-flags — the {id} slot takes the person’s email address (or the opaque id from any response), and each assignment carries who assigned it and when. PATCH /{id} is a partial update on both flag kinds: send only the fields that change (name, description, color, and designatesTrainer on skill flags); what is left out keeps its value. POST still requires name. Visibility exists only for people flags: one company-wide setting per audience at GET|PATCH /people-flags/visibility (administrators always see them — not configurable), and GET /people-flags/visibility/me resolves the answer for the acting identity.

​
Skill flags

The same lifecycle surface plus PATCH /{id}/trainer-designation. Dependencies and the guarded delete report counts per scope. Assignments live at /api/v1/skill-flag-assignments/{scope} where scope is careers, sections, skill-groups or skills — query with filters (?email= scopes to one person), POST applies in bulk and DELETE removes in bulk, both naming the people by email address:
Assignment rows in responses carry an opaque personId — use the person’s email when making requests.
The skill scope is not career-relative. Career, section and skill-group assignments carry the career; a skill-scope assignment keys off the skill alone and returns careerId: null. The four scopes are deliberately not squeezed into one shape.
Trainer tracking: GET /api/v1/skill-groups/{id}/trainer-count counts people carrying an enabled trainer-designating flag for the group.

​
Not published

FlagType — every assignment row internally duplicates the flag’s display name as a string, and it drifts when the flag is renamed. The API publishes the flag reference only.