⇠ Back to Dev HubSupport Center ›API Status ›Engineering Blog ›
API Reference

Team Auto-Dispatch

(Beta Feature)

Team Auto-Dispatch (Beta Feature)

Auto-Dispatching is meant to aid on-demand organizations who need means of dynamically dispatching tasks on the fly. The typical scheduled delivery organization would still use normal RO.

Auto-Dispatching is an operation that allows you to dispatch tasks assigned to a team to on-duty drivers. This operation ensures that tasks already assigned to the driver remain with them while automatically interleaving new tasks and potentially re-arranging the driver’s route. All routes return to the team’s hub by default but can be modified.

📘

Team Auto-Dispatch is a Scale plan or higher feature. Please contact your Onfleet representatives or support for more information.

Body Parameters

NameTypeDescription
maxTasksPerRouteIntegerOptional. Total number of tasks allowed on a route. Cannot be negative Integer. Default 100, cannot exceed 200.
taskTimeWindowArray of Unix Time in Seconds PrecisionOptional. This is the time window of tasks to include in the optimization. Param must be an array of length 2 in unix time in seconds precision, [start, end]. The default value is [now - 4 hours, now + 4 hours]. The end time cannot be in the past and cannot be more than 12 hours into the future. The total time frame cannot be longer than 16 hours.
scheduleTimeWindowArray of Unix Time in Seconds PrecisionOptional. This is the Driver's scheduled time window. Param must be an array of length 2 in unix time in seconds precision, [start, end]. The default value is is [now, now + 6 hours]. The start value cannot start more than 3 hours ago in the past. The ending value cannot be in the past and cannot end more than 16 hours into the future. The total time frame cannot be longer than 16 hours.
serviceTimeIntegerOptional. The default service time to apply in Minutes to the tasks when no task service time exists. Default is 2.
routeEndString (enumeration)Optional. Where the route will end. Valid values and their meaning:

teams://DEFAULT - Team’s hub

workers://ROUTING_ADDRESS - worker routing address

hub:// - return to a specific hub

null - end anywhere
maxAllowedDelayIntegerOptional. Time in Minutes a task can be late. Default value is 10, must be above 0

The dispatchId in the response is the Route Optimization ID for the resulting route. It is useful to keep that value and contact support in case there is any questions regarding to how the route was calculated.

📘

Unix Time

Onfleet API only accepts time formatted in Unix to the millisecond precision. Any other formats are not accepted and may produce unexpected results. For more information please see Data Types and Response Formats or free conversion tool online here.

curl -X POST "https://onfleet.com/api/v2/teams/K3FXFtJj2FtaO2~H60evRrDc/dispatch" -u "<key>:" -H 'content-type: application/json' -d '{"routeEnd": "workers://ROUTING_ADDRESS"}'

onfleet.teams.autoDispatch(id="FFqPs1KHayxorfA~~xIj0us4",body={"routeEnd": "workers://ROUTING_ADDRESS"})

onfleet.teams.autoDispatch("FFqPs1KHayxorfA~~xIj0us4",{"routeEnd": "workers://ROUTING_ADDRESS"})

$onfleet->teams->autoDispatch("FFqPs1KHayxorfA~~xIj0us4",["routeEnd"=> "workers://ROUTING_ADDRESS"])

{
    "dispatchId": "~HQ~Jann1TQlYrOweTKDVycl"
}

📘

Auto-Dispatch Webhook

If you are interested in the Auto-Dispatch Results, please refer to Webhook Payload Examples and set up autoDispatchJobCompleted for more information.

The filter.workers object will enable additional filtering for the auto-dispatch endpoint decide which worker to select and further streamline the auto-dispatch process based on the input criteria

This object has the following properties:

NameTypeDescription
maxContainerSizeIntegerOptional. This value filters workers who’s containers have more tasks than this value. This value has to be less or equal to maxTasksPerRoute.
vehicleTypeStringOptional. Only the values being set will be considered. If there are multiple workers online with different vehicle types within the team, then this field becomes necessary.

📘

When the max container size filter is not specified, maxTasksPerRoute is used as the container size filter.

When maxTasksPerRoute and filters.workers.maxContainerSize are both specified, maxTasksPerRoute only controls the final route length.

curl -X POST "https://onfleet.com/api/v2/teams/<teamId>/dispatch" -u "<apiKey>:" -H 'content-type: application/json' -d '{"maxTasksPerRoute": 50, "serviceTime": 4, "filters": { "workers": { "maxContainerSize": 2, "vehicleType": "TRUCK"}}}'

❗️

Maximum Distances for Team Auto Dispatch

Limitation: The maximum distances among Drivers, Hubs, and Tasks is 200 miles. Distances more than 200 miles will result in an error.

❗️

One Auto-dispatch per team at a time

Only one Team Auto-dispatch operation can be active at any given time. If there is another attempt to initiate an auto-dispatch call, an error message will appear: “Auto-Dispatch is already in progress for this team”

To mitigate this situation, we recommend setting up Webhook. autoDispatchJobCompleted.