API Documentation

This guide turns real-world scheduling requests into solver-friendly inputs without solver jargon. Use it as a support-friendly playbook when a client says, "Can it do X?" and you need to translate X into a plan.

We use first, second, third, and fourth priority to describe how strong a rule is. Higher priority beats lower priority when the solver must make tradeoffs. See Settings for details.

Quick toolkit

These are the levers you can combine to shape outcomes:

• Shift importance - Mark critical coverage as mandatory and nice-to-have coverage as optional. Shifts in your schedule
• Suggested and disliked employees - Nudge assignments per shift without forcing them. Shifts in your schedule
• Skills and teams - Control who is eligible to work where. Mapping skills and Spots
• Shift tags - Categorize work like "night", "peak", or "oncall". Shift tagging
• Priority levels and weights - Tune how strong each rule is. Settings
• Demand shaping - Make sure your inputs describe the real workload. Demands vs shifts
• Dependency rules - Require related coverage (for example, "if a supervisor is scheduled, ensure a support role exists"). Shift dependency rules

FAQ style scenarios

"We want all non-historic shifts aligned to a time of day"

Recommendation

• Use sameTimeOfDayForNonHistoricShifts instead of the requested-period variant.
• If you have a fixed, non-historic shift, the solver will align other non-historic shifts to that time of day.

Why it works

• It treats fixed, current shifts as anchors and snaps the remaining assignments to that time of day.

Watch for

• If you mix historic and non-historic shifts in the same period, only the non-historic ones are aligned.

"We should cover the busiest days first"

Try this

• Use MANDATORY for busy days and OPTIONAL for non-busy days.
• Add suggested employees for peak shifts to nudge coverage.
• Verify your demand model matches reality. Demands vs shifts

Why it works

• The solver prioritizes mandatory coverage and uses suggestions to break ties.

Watch for

• If everything is mandatory, the solver loses flexibility. Use third or fourth priority for the balancing rules here.

"Schedule limited availability employees first"

Try this

• Make sure all missing unavailability wishes are submitted first.
• If you plan to use a minimum-hours rule on your side, decide that up front and test it with real data.
• Add suggested employees for shifts that have very few feasible candidates.
• Consider smaller, more specific spots so the eligible pool is accurate. Spots

Why it works

• The solver is not assigning in a linear order. You need to reduce the candidate pool or nudge specific assignments.

Watch for

• Overusing suggestions can lead to the same people carrying too much load.

"Primary skill should win over secondary skill"

Try this

• Use suggested employees for shifts where a primary-skilled employee is preferred. Shifts in your schedule
• If primary staff share a special team, add that team to the spot and keep the team rule at third or fourth priority. Spots
• If primary staff share a contract, tag the shift as "primary preferred" and use category shift quotas at third or fourth priority. Shift tagging

Why it works

• These options express "prefer primary" without blocking secondary staff when coverage is tight.

Watch for

• If the priority is too high, you can unintentionally reduce coverage or fairness.
• Contract quotas influence totals across the period, not per-shift priority.

"We want fewer different people on the same spot each week"

Try this

• Enable single employee per week on the spot to prefer continuity. Spots
• Use suggested employees for critical continuity shifts.

Why it works

• Continuity is rewarded, but the solver can still break it when higher priorities require it.

Watch for

• If availability is tight, continuity goals can conflict with coverage and rest rules.

"We want fair distribution of the unpleasant shifts"

Try this

• Tag those shifts (for example, night or weekend) and enable load balance category shifts. Shift tagging
• Keep distribution at a lower priority than legal limits and unavailability.

Why it works

• The solver balances assignments inside the tag category without affecting other work as much.

Watch for

• If the eligible pool is too small, the solver will still concentrate work.

"We want consistency in a specific role, but only on high-demand days"

Try this

• Create a dedicated spot for those high-demand shifts and use single employee per week there.
• Keep other shifts on a general spot for flexibility.

Why it works

• You can target continuity without over-constraining the entire schedule.

Watch for

• Splitting spots increases input complexity, so keep naming and tags clear.

A simple decision guide

When a client asks for a change, translate it like this:

1. Coverage need - Is it mandatory or optional? Shifts in your schedule
2. Eligibility - Who is allowed to do it? Mapping skills and Spots
3. Preference - Who should be nudged? Shifts in your schedule
4. Category logic - Does it belong to a tag or rule set? Shift tagging
5. Priority tuning - What priority should it live at? Settings

If you want help translating a real schedule issue into inputs, send us a sample request and the outcome you want. We can suggest a minimal, testable change.

Release note style message you can reuse

Good morning, I hope you are well.

Following up on the meeting last week, we are ready to set the following live:

• We propose to replace sameTimeOfDayForRequestedPeriodShifts with sameTimeOfDayForNonHistoricShifts. This will make all shifts with historic: false be scheduled at a single time of day. If there is a fixed: true and historic: false shift, we use that as the anchor and align the remaining non-historic assignments to that time of day.

About the other investigations:

• If you want days with the most demand scheduled first, you can get more control by using staffingMode:
  • Use MANDATORY for busy days and OPTIONAL for non-busy days.
  • Keep this at third or fourth priority.
• If you want a category-level nudge, use shift tags and categoryShiftQuota. Shift tagging
  • Keep this at third or fourth priority.
• For employees with limited availability, please confirm you have submitted all unavailability wishes. We saw missing wishes last week. If you want to use the minimum-hours rule on your end, decide that before we overload anything else.
• For scheduling by qualification first:
  1. Set suggested employees for shifts with a preferred assignee and keep this at third or fourth priority.
  2. Put primary-skill employees into a special team and add that team to the spot. Keep the team rule at third or fourth priority. This is a clean nudge, but it can overload team usage if you already use teams for other logic.
  3. Tag the shift as primary preferred and set a contract quota for primary contracts. Keep it at third or fourth priority.

In the next release, we will also ship a new shift rotation option requested by another client. You will be able to read about it in the documentation once it is live, and we can walk through it if you want to consider it as well.

Are you okay with releasing the next constraint? We can do that today.