Access: System, Admin, and ClientAdmin users only.

The endpoint returns aggregate counts only for valid ClientEmployee rows in the requested company. It never exposes individual employee identifiers, names, SSNs, emails, or other personally identifiable data.

Employee and Contractor classification uses employment compensation evidence only. EmployeeLogic.GetEmployeeType is a reference for the relevant inputs; its SSN fallback is not used. Valid people without a current employment snapshot are counted in unclassifiedPersonCount and unclassifiedCountGroups.

Optional filters are residentialCountries, workCountries, departmentIds, positionIds, workLocationIds, statuses, and employeeTypes. groupBy is an optional strict single-value enum with supported values status, workCountry, residentialCountry, position, type, workLocation, and department. The former country token is no longer supported. Multi-value filters accept comma-separated values, pipe-separated values, repeated query keys, or mixed forms equivalently; values inside one filter are OR-ed and different filters are AND-ed. Empty supplied filters apply no constraint.

residentialCountries is a per-person filter and applies to classified and Unclassified people. The other filters are per-employment filters and require a current employment snapshot; when any per-employment filter is supplied, every Unclassified group reports zero. workLocationIds accepts values less than or equal to zero as the works-from-home sentinel.

When all filters are omitted, the endpoint returns the complete current-day company snapshot. When statuses is omitted, no employment-status constraint is applied; this intentionally differs from the timeline endpoint, where omitted statuses default to active.

When groupBy is supplied, workforceCountsByGroup is added as an observed-only positive group collection ordered by group key, legislative, and employee type. The collection excludes snapshot-less people, while the existing fixed groups and top-level aggregates remain authoritative and unchanged. Status grouping uses the same 3-bucket active/terminated/inactive vocabulary as the statuses filter, and type grouping uses employee/contractor. The residentialCountry dimension also emits snapshot-less people in the separate residentialCountrySnapshotlessGroups[] collection, with no employeeType field. Work-location keys use {workLocationId, isWorkFromHome}, and the total emitted workforceCountsByGroup[] item count is capped at 1,000.

Per-field filter validation uses ApiValidationException with machine-readable error codes INVALID_COUNTRY_CODE and INVALID_POSITIVE_ID. Enum model-binding errors use apiResult.Code = "data_validation_error". Enum query parameters accept defined numeric enum values as input; unsupported string or numeric values still fail validation, and multi-value groupBy submissions remain unsupported. Company-not-found uses NotFound(message); total-group cap exceedance uses BadRequest(message); unexpected classification/data failures use InternalServerError(message). No endpoint-specific error-code prefix is introduced.