Route Optimization Remove Manual Assigned Tasks

This work with jobType: "ON-DEMAND"

The optional bypassManualAssignments parameter tells an on-demand optimization to leave alone any task a dispatcher assigned to a driver by hand in the Onfleet dashboard. Those tasks are taken out of the optimization: they stay with the driver they were assigned to, and the optimizer neither re-orders them nor moves them to another driver. Use it when dispatchers sometimes override the optimizer and you don't want the next on-demand run to undo their choice. If you leave it out, optimization works the same as today.

Example Request

curl -X POST "https://onfleet.com/api/v2/optimizations/scheduled" \
     -u "<your_onfleet_api_key>:" \
     -H "Content-Type: application/json" \
     -d '{
  "jobType": "ON-DEMAND",
  "bypassManualAssignments": true,
  "autoApplyAssignment": false,
  "tasks": [
    "kH3vQ2pXr8sT~mWz1bYcNd4e",
    "Lp9*aRt5uVw0xYz2BcDeFg6h",
    "Mq1sT7uVw~3xYz5AbCdEfGh8",
    "Nr4uVw9xYz*6AbCdEfGh1jKl"
  ],
  "teams": {
    "9PVeSqj*RxI46~aD*M812DkY": ["mQpa~QD~LYcG89bPdig8sREj", "tR6~kLmN2oPqRsTuVwXyZ0ab"]
  },
  "date": 1794016232632,
  "timezone": "America/Vancouver",
  "mode": 0,
  "serviceTime": 5,
  "maxViolationTime": 0,
  "maxTasksPerRoute": 30,
  "schedulingMethod": 1,
  "routeStart": "hub://~nNn~t7pJBiWQuYR6ZqLbAeg",
  "routeEnd": "hub://~nNn~t7pJBiWQuYR6ZqLbAeg",
  "defaultSchedule": [
    {
      "date": 1794016232632,
      "slots": [{ "start": "0000", "end": "2359" }],
      "owner": "gz6~YVrx7HVI34ecvWOG1LfB",
      "timezone": "America/Vancouver"
    }
  ]
}'

The first three tasks are already on a driver's route and the fourth is a new order. If a dispatcher dragged the first task onto that driver in the dashboard, the optimization plans around the other three and leaves the first task where it is.

Route Optimization Behaviour

Which tasks are left out: A task is left out when its most recent assignment is a dashboard user assigning it to a driver. You can check this with Get Single Task and ?assignmentHistory=true: the last entry has actionContext.type "ADMIN", no actionContext.source, and containerDescription.type "WORKER". API assignments show "API", and tasks placed by an earlier optimization show "ADMIN" with source: "ROUTE_OPTIMIZATION", so neither is left out. Every task created through the API starts with an "API" entry for the organization container.

Only the most recent assignment counts: If a dispatcher assigns a task in the dashboard and it is later reassigned through the API, it is no longer left out.

Only tasks you send: The optimizer only considers the tasks listed in tasks, including tasks already on a driver's route. To keep a driver's existing stops in the plan, list them in tasks. This parameter only affects dashboard-assigned tasks that you include; tasks you don't send are never touched.

What the result shows: A left-out task does not appear anywhere in Get Optimization Status: not in summary.workers.<workerId>.tasks and not in unassignedTasks. The driver's count, travelDistance, travelTime and routeOnDutyTime are calculated without it. In testing, leaving out one stop dropped the planned route from 8,112 m to 7,716 m, even though the driver still has to make that stop. Planned times on that route don't account for the left-out stop.

After Apply: Apply Optimization Results keeps a left-out task with the same driver. It isn't unassigned or moved to another driver, though its position in the driver's task list can change. In testing it moved to the front of the list.

At least one new task: An on-demand optimization needs at least one task that isn't already assigned. If every task you send is already on a driver, or is left out by this parameter, Start Route Optimization fails with No new/unassigned tasks found to optimize. This happens with or without bypassManualAssignments.

Organization default: You can set bypassManualAssignments on your organization's route optimization profile instead of sending it on each request. The default applies to on-demand optimizations that don't send their own value. A value in the request always wins.

Errors

Validation errors return HTTP 400 with error code 1000. The specific reason is in message.cause:

{
  "code": "InvalidContent",
  "message": {
    "error": 1000,
    "message": "The values of one or more parameters are invalid.",
    "cause": "bypassManualAssignments is supported only for ON-DEMAND and REOPTIMIZE optimizations"
  }
}