Get worker turnover totals for a specific employer
POST/v1/reporting/:employer_id/reports/worker_turnover/totals
Retrieves aggregate turnover metrics for a single period: beginning/end headcount, total/voluntary/involuntary turnover, headcount reduction, new hires, rehires, and turnover rate. Powers the 'At a Glance' and 'Headcount Variation' UI sections.
Request
Path Parameters
Use me (recommended) to resolve the employer associated with your OAuth credentials, or pass your numeric employer ID. The value must match the employer your token is issued for.
Query Parameters
Start date for the period (ISO 8601 format: YYYY-MM-DD)
End date for the period (ISO 8601 format: YYYY-MM-DD)
Responses
- 200
- 400
- 401
- 403
- 404
- 429
- 500
- 504
Successfully retrieved turnover totals
- */*
- Schema
- Example (from schema)
Schema
Array [
]
request
object
venue_and_area_ids
object[]
The venue ID
List of area IDs within this venue. Omit/empty = all areas, [0] = venue-level only, [5843] = specific area(s), [0, 5843] = venue-level + specific. Note: 0 represents NULL areas.
totals
object
metadata
object
{ "request": { "employer_id": 0, "deployment_code": "string", "from_date": "string", "to_date": "string", "venue_and_area_ids": [ { "venue_id": 2057, "area_ids": [ 5811, 5812 ] } ] }, "totals": { "beginning_headcount": 0, "total_turnover": 0, "voluntary_turnover": 0, "involuntary_turnover": 0, "headcount_reduction": 0, "new_hires": 0, "rehires": 0, "new_and_returning_hires": 0, "subtotal": 0, "end_headcount": 0, "turnover_rate": 0 }, "metadata": { "employer_id": 0, "to_date": "string", "period_from": "string", "period_granularity": "string", "venue_ids": [ 0 ], "area_ids": [ 0 ], "generated_at": "2026-07-07T10:51:42.819Z" }}Invalid request parameters. The response body follows the ErrorResponse schema.
- application/json
- Schema
- Example (from schema)
Schema
Human-readable error message.
Machine-readable error classification (e.g. VALIDATION_ERROR, TIMEOUT_ERROR, CIRCUIT_BREAKER_OPEN).
Whether the request can be safely retried.
When the error occurred.
{ "error": "string", "errorType": "string", "retryable": true, "timestamp": "2026-07-07T10:51:42.820Z"}Missing or invalid Bearer token.
The authenticated client is not authorized for the requested employer_id. The employer_id in the path must match the employer your token is issued for.
Unknown endpoint, or reporting access is not enabled for this client.
Rate limit exceeded. Retry after the interval indicated by the Retry-After response header.
Internal server error. The response body follows the ErrorResponse schema.
- application/json
- Schema
- Example (from schema)
Schema
Human-readable error message.
Machine-readable error classification (e.g. VALIDATION_ERROR, TIMEOUT_ERROR, CIRCUIT_BREAKER_OPEN).
Whether the request can be safely retried.
When the error occurred.
{ "error": "string", "errorType": "string", "retryable": true, "timestamp": "2026-07-07T10:51:42.820Z"}Upstream timeout. The reporting backend did not respond in time; the response body is {"error": "upstream timeout"}.