Access: System, Admin, and ClientAdmin users only.

The endpoint returns aggregate counts only. It never exposes individual employee identifiers, names, SSNs, emails, addresses, or an Unclassified group. A person without an overlapping valid BaseEmployment is excluded from that period. A person with multiple overlapping BaseEmployments that classify to different (legislative, employeeType) tuples contributes once to each distinct tuple.

Multi-value filters accept comma-separated values, pipe-separated values, repeated query keys, or mixed forms equivalently. Values inside one filter are OR-ed; different filters are AND-ed. Empty supplied filters apply no constraint. When statuses is omitted entirely, the endpoint defaults to active; when ?statuses= is supplied explicitly, no status constraint is applied. 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. Filtering always narrows the BaseEmployment rows before grouping; grouping never bypasses active filters.

When groupBy is omitted, no grouping fields are serialized and the response shape is unchanged. When it is supplied, the envelope emits knownGroups[] and knownGroupCount as the ordered union of observed group keys across the response window. Each data point emits observed positive-count groups[] by default; with zeroFill set to true, every data point emits one entry per known group key with zero-count entries for absent keys. The existing data-point-level scalars and fixed workforceCountGroups[] remain authoritative and non-zero. Group keys are non-PII and shaped as a 3-bucket status string, work/residential country string, position or department integer, employee-type string, or {workLocationId, isWorkFromHome}. Rows with null source values for the selected dimension are excluded only from the caller-selected grouping and still count in the existing data-point aggregates.

Status grouping uses the same 3-bucket vocabulary as statuses: active, terminated, and inactive. Because omitted statuses defaults to active, a naive ?groupBy=status request emits only the active bucket; callers that need all statuses must pass ?statuses=active,terminated,inactive or ?statuses=. The type group key uses the employee/contractor vocabulary from employeeTypes.

The enum query parameters granularity, statuses, employeeTypes, and groupBy accept defined numeric enum values as input in addition to their string wire values. Unsupported string or numeric values still return model-validation errors; multi-value groupBy submissions remain unsupported. Controller per-field validation uses machine-readable error codes INVALID_DATE_RANGE, INVALID_COUNTRY_CODE, and INVALID_POSITIVE_ID. Range-cap violations use BadRequest(message) and apiResult.Code = "400"; default grouping keeps the 5,000 observed-entry cap, while zeroFill uses a 200 distinct-key cap. Company-not-found uses NotFound(message) and apiResult.Code = "404". No endpoint-specific TWT_* codes are introduced.

Weekly and bi-weekly periods use the caller role's existing week rules via CurrentRole.GetWeekOfYearInfo(date); Global employee roles observe Monday-based periods, while other roles observe Sunday-based periods. Bi-weekly periods are a continuous 14-day grid derived from the role-specific 2020 reference anchor and do not reset at year boundaries. Requests producing more than 500 data points return 400 Bad Request; data points are never truncated and granularity is never silently coarsened.