Get shift fulfilment data with flexible aggregation
POST/v1/reporting/:employer_id/reports/shift_fulfilment/aggregated
Retrieves shift fulfilment data aggregated by time and optional dimensions (venue, role, area, shift rate type, worker type). Time grouping is always required (DAY, WEEK, MONTH, YEAR, DAY_OF_WEEK, or OVERALL for entire date range); other dimensions are optional.
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
Time period for aggregation. Must be one of: DAY, WEEK, MONTH, YEAR, DAY_OF_WEEK (groups by day of week, US starts with Sunday, UK starts with Monday), OVERALL (aggregates across entire date range)
Start date for filtering (ISO 8601 format: YYYY-MM-DD)
End date for filtering (ISO 8601 format: YYYY-MM-DD)
Responses
- 200
- 400
- 401
- 403
- 404
- 429
- 500
- 504
Successfully retrieved aggregated shift fulfilment data
- */*
- Schema
- Example (from schema)
Schema
Array [
]
Array [
]
request
object
The employer ID
Deployment code (US or UK)
Start date of the query
End date of the query
Time grouping period (DAY, WEEK, MONTH, YEAR)
List of dimensions used for grouping
filters
object
Filters applied to the query
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.
report
object
insights
object[]
Aggregated insights data points
Period start date (ISO 8601 format)
Period end date (ISO 8601 format)
Time granularity
dimensions
object
Dimensional breakdown (venue, role, area, etc.)
metrics
object
Aggregated metrics for this period/dimension
Total number of shifts posted
Total number of shifts booked
Percentage of shifts booked
Total number of unfilled shifts
Percentage of unfilled shifts
Total number of shifts worked
Percentage of shifts worked
Total number of no-shows
Percentage of no-shows
Total hours scheduled
Total hours worked
Total number of overbooked shifts
Total true demand (actual shifts needed)
Percentage of shifts worked relative to true demand
Percentage of shifts booked relative to true demand
Percentage of shifts unfilled relative to true demand
Percentage of no-shows relative to true demand
metadata
object
Total number of records returned
Total number of unique time periods
Total number of unique dimensional groups
Query execution time in milliseconds
Timestamp when the response was generated
Current page number (if pagination is used)
Number of records per page (if pagination is used)
{ "request": { "employer_id": 0, "deployment_code": "string", "from_date": "string", "to_date": "string", "time_grouping": "string", "grouped_by": [ "string" ], "filters": { "venue_and_area_ids": [ { "venue_id": 2057, "area_ids": [ 5811, 5812 ] } ], "role_ids": [ 0 ], "shift_rate_type_ids": [ 0 ], "worker_types": [ "string" ] } }, "report": { "insights": [ { "period_start": "2024-01-01", "period_end": "2024-01-07", "granularity": "WEEK", "dimensions": { "venue_id": 0, "venue_name": "string", "role_id": 0, "role_name": "string", "area_id": 0, "area_name": "string", "shift_rate_type_id": 0, "worker_type": "string" }, "metrics": { "shifts_posted": 120, "shifts_booked": 115, "shifts_booked_percentage": 95.83, "shifts_unfilled": 5, "shifts_unfilled_percentage": 4.17, "shifts_worked": 110, "shifts_worked_percentage": 91.67, "no_shows": 5, "no_shows_percentage": 4.35, "hours_scheduled": 960, "hours_worked": 920, "overbook_shifts": 2, "true_demand": 120, "true_fulfilment_percentage": 85, "true_booked_percentage": 87.5, "true_unfilled_percentage": 12.5, "true_no_show_percentage": 5 } } ] }, "metadata": { "total_records": 0, "total_periods": 0, "total_groups": 0, "execution_time_ms": 0, "generated_at": "2026-07-07T10:51:42.814Z", "current_page": 0, "per_page": 0 }}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.815Z"}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.815Z"}Upstream timeout. The reporting backend did not respond in time; the response body is {"error": "upstream timeout"}.