First a clarification of terms to avoid confusion as I answer your question - v2.workforcemanagement.businessunits.{id}.shorttermforecasts is not an endpoint, but a notification topic. Endpoints look more like "/api/v2/some/path/structure".
The topic v2.workforcemanagement.businessunits.{id}.shorttermforecasts is for progress and completion notifications for forecast generation, and the schema is the same as the response schema, and with the same definitions. It does not return the actual raw forecast data.
- Planning groups are a snapshot of your actual planning group configuration at the time of forecast generation. This is because updating the planning group after the forecast is generated will not cause the forecast to automatically update - if an updated forecast is desired following a modification to the planning group configuration, a new forecast must be generated.
- On a freshly generated forecast, there always will be 0 modifications. Modifications are for forecast administrators to manually override portions of a forecast if desired. For most cases these shouldn't be needed, but an example would be a modification to the forecast if the administrator knows the contact center will be closed for a given time that isn't reflected in the generated forecast.
The documentation for the forecast generation route can be found here, with documentation for each of the fields in the notification topic you asked about:
POST /api/v2/workforcemanagement/businessunits/{businessUnitId}/weeks/{weekDateId}/shorttermforecasts/generate
You'll find descriptions for each result field under the "Api Responses" -> 202 section.
Intervals are 15 minute intervals (for short term forecasts, long term forecasts the interval is 1 day), the index 0 corresponds to the same time as referenceStartDate, and each following index is exactly 15 minutes after the previous. To get a specific interval for a specific time, you calculate the number of minutes that time is after referenceStartDate, divide by 15, and that will be the interval number you want.
The number of intervals is fixed at the exact number of intervals covered by the forecast - intervals with no data will be zero filled. One thing to note is that forecasts always have an extra day (we call it 8th day) to cover some scheduling edge cases, for example when a shift crosses midnight into the next week. This only applies to the last week of the forecast - if you have a two week forecast the first week will be the normal 7 days, the second will have an extra "8th day". This concept applies to both forecasts and agent schedules.
So for a standard one week forecast that does not cross a daylight savings time boundary, it would be (8 days x 24 hours x 60 minutes) / 15, or 768 intervals total.
For a week that does cross a DST boundary in the time zone specified for the business unit, you would add or subtract the number of intervals added or removed by the transition (fall back 1 hour, add 4 additional intervals for the "extra" hour, when you "spring forward" and skip an hour, subtract 4 intervals from the total). This adjustment to the number of total intervals only applies to short term forecasts, since long term forecasts have full day intervals.
To get the actual forecast data (with modifications applied), once the forecast has completed its generation you will use the following endpoint:
GET /api/v2/workforcemanagement/businessunits/{businessUnitId}/weeks/{weekDateId}/shorttermforecasts/{forecastId}/data
This route will supply the actual metric values per interval.
------------------------------
Brian Trezise
Genesys - Employees - Lead Software Engineer
------------------------------
Original Message:
Sent: 04-15-2025 15:48
From: Liam Rowell
Subject: The eventbridge endpoint v2.workforcemanagement.businessunits.{id}.shorttermforecasts
For the eventbridge endpoint v2.workforcemanagement.businessunits.{id}.shorttermforecasts
1. Does the number of planning groups correlate a set of metric values per interval? i.e. will there be the same number of modification sets as there are planning groups?
2. What is the definition of interval index?
#Integrations
------------------------------
Liam Rowell
Intern
------------------------------