I'mBoard API Docs

Total number of employees (W-2 / direct-employment equivalents) across all departments at period end. The base denominator for nearly every other HR ratio — turnover rate, revenue per FTE, payroll as % of burn — so getting the snapshot date and the FTE-vs-headcount convention right matters. CANONICAL HEADCOUNT (#2056): this single KPI carries BOTH the plan and the reported figure via the scenario axis (#2019) — scenario=`budget` is the board-approved headcount plan (formerly the separate, now-deprecated `hr.approved_headcount_budget`), and scenario=`actual` is the reported end-of-period count. Budget-vs-actual variance is read off the two scenarios of this one definition. Common pitfall: mixing headcount (people) with FTE (capacity) — they diverge whenever part-time, contractor, or shared-services arrangements exist. Document the convention (typically "FTE-equivalent, employees only, end-of-period") at the board level once and apply consistently. — HR KPI, I'mBoard-authored (editorial tier).

I'mBoard-authored (editorial tier)

No public third-party standard anchors this KPI yet, so I'mBoard authors and maintains the definition — transparently labeled as editorial tier. See the ontology methodology for the published vs editorial tier system and the back-attribution workstream.

Rogue ID: hr.total_headcount Type: Number Domain: HR

Definition

Total number of employees (W-2 / direct-employment equivalents) across all departments at period end. The base denominator for nearly every other HR ratio — turnover rate, revenue per FTE, payroll as % of burn — so getting the snapshot date and the FTE-vs-headcount convention right matters. CANONICAL HEADCOUNT (#2056): this single KPI carries BOTH the plan and the reported figure via the scenario axis (#2019) — scenario=budget is the board-approved headcount plan (formerly the separate, now-deprecated hr.approved_headcount_budget), and scenario=actual is the reported end-of-period count. Budget-vs-actual variance is read off the two scenarios of this one definition. Common pitfall: mixing headcount (people) with FTE (capacity) — they diverge whenever part-time, contractor, or shared-services arrangements exist. Document the convention (typically "FTE-equivalent, employees only, end-of-period") at the board level once and apply consistently.

Formula

Count of active employees at period end. Convention: FTE-equivalent (a 0.5 FTE counts as 0.5), employees only (contractors tracked separately in `hr.total_contractors`). Snapshot is end-of-period unless the board has explicitly adopted an average-headcount convention for ratio math. The budget scenario (scenario=`budget`) holds the board-approved plan for the same definition; actuals (scenario=`actual`) hold the reported count.

Why it matters

The denominator for every HR ratio the board reads — turnover %, revenue/FTE, payroll as % of burn. Drift in this number without a corresponding hiring-plan update is a leading signal of unmanaged growth or quiet attrition.

How to interpret

Read budget-vs-actual off this one KPI: scenario=budget is the board-approved headcount plan, scenario=actual is the reported count (#2056 — this replaces the deprecated hr.approved_headcount_budget). A delta above ±5% without a board note typically warrants explanation. Stage norm for SaaS (industry folk-wisdom, not citation-grade): seed 5–15, Series A 20–50, Series B 50–150, Series C 150–400.

Calculation policy

How an AI agent should compute this KPI from messy company data. Free-text rules consumed at reasoning time — not a deterministic DSL. The most common ways to get this wrong are listed under Common miscomputations.

Inclusion rules

Count of active W-2 / direct-employment-equivalent employees across all departments, measured AS OF the period-end date (point-in-time snapshot, not an average — unless the board has formally adopted average-headcount for ratio math, in which case state it).
Convention is FTE-equivalent: a 0.5 FTE counts as 0.5, not 1. Pin this convention once at the board level and apply it identically everywhere headcount feeds a ratio.
When reading budget-vs-actual, scenario=budget holds the board-approved headcount plan and scenario=actual holds the reported end-of-period count — both ride this single canonical KPI (#2056).

Exclusion rules

Contractors, 1099s, consultants, and agency labor — those live in hr.total_contractors. Folding them in is the single most common headcount error and corrupts every downstream ratio.
Open (unfilled) requisitions — an approved-but-vacant role is hr.open_positions, not a head.
Accepted offers whose start date has not yet landed in the period — they become heads via hr.new_hires when they actually start.
Employees whose last day fell on or before the period-end snapshot date — they have already left the count.

Required inputs

Active-employee roster as of the period-end date with employment type (W-2 vs contractor) and FTE fraction per person.
The board-adopted convention flag: FTE-equivalent vs raw head, and end-of-period vs average.
Department / function attribution if the board reads headcount by team.

Data-source priority

HRIS system of record (Rippling / Gusto / BambooHR / Workday) active-employee report at period close.
Payroll register as a cross-check on who was actually paid in the period.
Finance AP / contractor detail to confirm contractors were NOT swept into the employee count.

Edge cases

Part-time and job-share arrangements: convert to FTE fraction — two 0.5 FTEs are 1.0, not 2.0, under the FTE convention.
Employees on unpaid leave / sabbatical: typically still counted as active heads; document the treatment and apply it consistently across periods.
Acquisition or acqui-hire mid-period: the acquired team joins headcount on their effective start date, not the deal-close date — keep the two distinct.
Shared-services or PEO-employed staff working full-time under company direction: decide once whether they count as heads or contractors and never flip mid-series.

Validation checks

Prior headcount + hr.new_hires − (hr.voluntary_exits + hr.terminations) should reconcile to current headcount within the period; an unexplained gap means a hire/exit was mis-dated or a contractor was swept in.
Headcount should move in step with hr.payroll_run_rate; a headcount jump with flat payroll (or vice versa) flags a counting or classification error.
A delta above ±5% vs the scenario=budget plan without a board note typically warrants explanation.

Common miscomputations

Including contractors in the head count — inflates the denominator and understates every per-FTE productivity and turnover ratio.
Counting raw heads instead of FTE-equivalent when part-time / job-share arrangements exist — overstates capacity.
Using a mid-period or average snapshot in one report and end-of-period in another — the two conventions silently disagree and make turnover math unreproducible.
Counting accepted-but-not-started offers as heads — they belong to next period via hr.new_hires.

hr.headcount_change
hr.approved_headcount_budget
hr.new_hires
hr.voluntary_exits
hr.terminations
hr.total_contractors
hr.arr_per_fte

Source

I'mBoard editorial — authored and maintained by I'mBoard, first published 2026-04-01. No third-party standard is cited for this KPI; when one emerges, the definition is back-attributed and promoted to the published tier (a minor version bump). Read the ontology methodology for the published vs editorial tier system, attribution rules, and dispute process.