Get shift fulfilment data for a specific employer

POST 
/v1/reporting/:employer_id/reports/shift_fulfilment

Retrieves shift fulfilment data with optional filtering by date range, venue, role, and worker type

Request

Path Parameters

employer_id stringrequired

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

from_date stringrequired

Start date for filtering (ISO 8601 format: YYYY-MM-DD)

to_date stringrequired

End date for filtering (ISO 8601 format: YYYY-MM-DD)

Responses

200

Successfully retrieved shift fulfilment data

*/*

Schema

Schema

request

object

employer_id int32

deployment_code string

from_date string

to_date string

venue_and_area_ids

object[]

Array [

venue_id int32required

The venue ID

area_ids int32[]

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

shifts

object[]

Array [

SHIFT_DATE string

NOTICE_PERIOD string

SHIFT_START_TIME string

SHIFT_END_TIME string

VENUE_NAME string

AREA_NAME string

TIMEZONE string

JOB_TITLE string

SHIFTS_POSTED int32

SHIFTS_BOOKED int32

SHIFTS_BOOKED_PERCENTAGE double

SHIFTS_UNFILLED int32

SHIFTS_UNFILLED_PERCENTAGE double

SHIFTS_WORKED int32

SHIFTS_WORKED_PERCENTAGE double

NO_SHOWS int32

NO_SHOWS_PERCENTAGE double

HOURS_SCHEDULED double

HOURS_WORKED double

AVERAGE_WORKER_RATING double

OVERBOOK_SHIFTS int32

ACCEPTED_ABSENCES int32

TRUE_DEMAND int32

TRUE_FULFILMENT_PERCENTAGE double

TRUE_BOOKED_PERCENTAGE double

TRUE_UNFILLED_PERCENTAGE double

TRUE_NO_SHOW_PERCENTAGE double

PUBLISHED_AT string

OVERBOOK_SHIFT_DEMAND int32

AGENCY_RETRO_DEMAND int32

ADHOC_SHIFT_DEMAND int32

TIMECLOCK_SHIFT_DEMAND int32

SHIFT_ID int32

]

metadata

object

employer_id int32

to_date string

period_from string

period_granularity string

venue_ids int32[]

area_ids int32[]

generated_at date-time

Example (from schema)

{
  "request": {
    "employer_id": 0,
    "deployment_code": "string",
    "from_date": "string",
    "to_date": "string",
    "venue_and_area_ids": [
      {
        "venue_id": 2057,
        "area_ids": [
          5811,
          5812
        ]
      }
    ]
  },
  "report": {
    "shifts": [
      {
        "SHIFT_DATE": "string",
        "NOTICE_PERIOD": "string",
        "SHIFT_START_TIME": "string",
        "SHIFT_END_TIME": "string",
        "VENUE_NAME": "string",
        "AREA_NAME": "string",
        "TIMEZONE": "string",
        "JOB_TITLE": "string",
        "SHIFTS_POSTED": 0,
        "SHIFTS_BOOKED": 0,
        "SHIFTS_BOOKED_PERCENTAGE": 0,
        "SHIFTS_UNFILLED": 0,
        "SHIFTS_UNFILLED_PERCENTAGE": 0,
        "SHIFTS_WORKED": 0,
        "SHIFTS_WORKED_PERCENTAGE": 0,
        "NO_SHOWS": 0,
        "NO_SHOWS_PERCENTAGE": 0,
        "HOURS_SCHEDULED": 0,
        "HOURS_WORKED": 0,
        "AVERAGE_WORKER_RATING": 0,
        "OVERBOOK_SHIFTS": 0,
        "ACCEPTED_ABSENCES": 0,
        "TRUE_DEMAND": 0,
        "TRUE_FULFILMENT_PERCENTAGE": 0,
        "TRUE_BOOKED_PERCENTAGE": 0,
        "TRUE_UNFILLED_PERCENTAGE": 0,
        "TRUE_NO_SHOW_PERCENTAGE": 0,
        "PUBLISHED_AT": "string",
        "OVERBOOK_SHIFT_DEMAND": 0,
        "AGENCY_RETRO_DEMAND": 0,
        "ADHOC_SHIFT_DEMAND": 0,
        "TIMECLOCK_SHIFT_DEMAND": 0,
        "SHIFT_ID": 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.818Z"
  }
}

400

Invalid request parameters. The response body follows the ErrorResponse schema.

application/json

Schema

Schema

error string

Human-readable error message.

errorType string

Machine-readable error classification (e.g. VALIDATION_ERROR, TIMEOUT_ERROR, CIRCUIT_BREAKER_OPEN).

retryable boolean

Whether the request can be safely retried.

timestamp date-time

When the error occurred.

Example (from schema)

{
  "error": "string",
  "errorType": "string",
  "retryable": true,
  "timestamp": "2026-07-07T10:51:42.818Z"
}

401

Missing or invalid Bearer token.

403

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.

404

Unknown endpoint, or reporting access is not enabled for this client.

429

Rate limit exceeded. Retry after the interval indicated by the Retry-After response header.

500

Internal server error. The response body follows the ErrorResponse schema.

application/json

Schema

Schema

error string

Human-readable error message.

errorType string

Machine-readable error classification (e.g. VALIDATION_ERROR, TIMEOUT_ERROR, CIRCUIT_BREAKER_OPEN).

retryable boolean

Whether the request can be safely retried.

timestamp date-time

When the error occurred.

Example (from schema)

{
  "error": "string",
  "errorType": "string",
  "retryable": true,
  "timestamp": "2026-07-07T10:51:42.818Z"
}

504

Upstream timeout. The reporting backend did not respond in time; the response body is {"error": "upstream timeout"}.

Loading...

 

Was this page helpful?