This section relates to Initialize Auto-Dispatch Route Optimization , which requires Route Plans to be enabled and may depend on your Onfleet subscription plan. For details on feature availability, please contact [email protected].
Using this endpoint initializes a standard scheduled route optimization workflow and creates routes for generic vehicles, rather than assigning them directly to drivers. The request requires route optimization (RO) parameters and will respond with any issues. If successful, it returns a summary and an ID for the next step in the optimization process.
Once everything is set up and confirmed, use Start Route Optimization to initiate the calculation.
Note: If you are using the v3 optimization engine, you can specify multiple vehicle types. The classic optimization engine can consider only one vehicle type at a time.
JSON payload fields for setting up the RO using vehicle:
Initial base field: jobType:
| Name | Type | Description |
|---|---|---|
| jobType | string | Required. The only acceptable value here is DEFAULT |
Other base fields:
| Name | Type | Description |
|---|---|---|
| optimizationType | string | Required. The only acceptable value here is VEHICLES. |
| maxTasksPerRoute | number | Required. How many tasks should be assigned to each worker. This overrides the per vehicle |
| date | Time in Unix | Required. This will need to be in milliseconds precision and will need to be aligned with the completeBefore and completeAfter time range specified on the individual task. |
| timezone | string | Required. Which timezone is considered. |
| mode | number | Required. This corresponds to the Optimization mode on the Dashboard. Put 0 for Minimize Distance Driven, 1 Always Arrive On Time and 2 for Balance Distance and Time. |
| serviceTime | number | Required. How many minutes a driver would spend on each task. This will adds to the time calculation of the RO and is considered part of the delivery time. |
| tasks | Array of Task Objects | Required. Task IDs to be considered for the RO. |
| teams | Object | Required. The Team IDs and their associated workers' ID for Route Optimization to consider. |
| schedulingMethod | number | Required. Which schedule would be used for the RO to consider; put 0 for default schedule, put 1 for Driver's Schedule. |
| routeStart | string | Where the Route should start. |
| routeEnd | string | Where the Route would end. |
| maxViolationTime | number | Time in minutes that the RO should consider. This is important if mode is Always arrive on Time. Will result in |
| avoidTolls | boolean | Should the RO considered toll roads. |
| balanceRoutes | boolean | Should the RO consider balance tasks across all drivers |
| allowMissingLinkedTasks | boolean | Should the RO consider missing Linked-Tasks. |
| createEndRouteTask | boolean | Should the RO create an End route Task at the Hub |
| optimizationByVehicle | Object | Required. Please see below for further explanation. |
| defaultSchedule | Object | Please see Get worker's schedule for how Schedule object looks like. |
The distinguished part of this RO by API section
optimizationByVehicle Object:
| Name | Type | Description |
|---|---|---|
| team | string | The Team IDs and their associated workers' ID for Route Optimization to consider. |
| vehicleTypes | Object | Please see below examples for the breakdown of this object |
For thevehicleTypes Object field, you must include all of the fields listed in the table below:
| Name | Type | Description |
|---|---|---|
| walking | Object | Required. See below for further explanation |
| bicycle | Object | Required. See below for further explanation |
| motorcycle | Object | Required. See below for further explanation |
| car | Object | Required. See below for further explanation |
| truck | Object | Required. See below for further explanation |
each one of the vehicle types are required, and they all have the same following fields:
| Name | Type | Description |
|---|---|---|
| selected | boolean | This field determines what types of vehicle(s) would be considered for the RO. Put true if you would like to include this vehicle type; put false to leave it off. |
| count | number | How many vehicles of this type should be considered for the RO. |
| maxTasksPerRoute | number | How many tasks for each of the drivers considered for the RO. |
| capacity | number | How many capacity each vehicle has it. |
{
"jobType": "DEFAULT",
"optimizationType": "VEHICLES",
"maxTasksPerRoute": 0,
"date": 1761779759419,
"timezone": "America/Los_Angeles",
"mode": 1,
"serviceTime": 30,
"tasks":
[
"iHz~bG*Esph92oQRS*53p~6w",
"uNVNORDYNfGzMsH5Jt3n48F3",
"ZSfzR90IeDJrjxWBLHbboOjA",
"NUv5ZPWDGMvQd*~x1d8EPRCI"
],
"teams":
{},
"schedulingMethod": 1,
"routeStart": "hub://FK9Uny9sQzcvBmEqHXqwWSeV",
"routeEnd": "hub://FK9Uny9sQzcvBmEqHXqwWSeV",
"maxViolationTime": 3,
"avoidTolls": true,
"balanceRoutes": true,
"allowMissingLinkedTasks": false,
"createEndRouteTask": false,
"optimizationByVehicle":
{
"team": null,
"vehicleTypes":
{
"walking":
{
"selected": false,
"count": null,
"maxTasksPerRoute": null,
"capacity": null
},
"bicycle":
{
"selected": false,
"count": null,
"maxTasksPerRoute": null,
"capacity": null
},
"motorcycle":
{
"selected": false,
"count": null,
"maxTasksPerRoute": null,
"capacity": null
},
"car":
{
"selected": true,
"count": 1,
"maxTasksPerRoute": 5,
"capacity": 1
},
"truck":
{
"selected": false,
"count": null,
"maxTasksPerRoute": null,
"capacity": null
}
}
},
"defaultSchedule":
[
{
"date": 1761779759419,
"owner": "nYrkNP6jZMSKgBwG9qG7ci3J",
"timezone": "America/Los_Angeles",
"slots":
[
{
"start": "0900",
"end": "2359"
}
]
}
]
}{
"id": "j6BWjQvO31tofLgktcNcnqGQ",
"issues": [
{
"type": "warning",
"message": "Task b96426cc is more than 200 miles (321 KM) away from any hub.",
"entityType": "task",
"entityId": "iHz~bG*Esph92oQRS*53p~6w",
"shortId": "b96426cc",
"reason": "too-far-from-hub"
},
{
"type": "warning",
"message": "Task 43dca744 is more than 200 miles (321 KM) away from any hub.",
"entityType": "task",
"entityId": "uNVNORDYNfGzMsH5Jt3n48F3",
"shortId": "43dca744",
"reason": "too-far-from-hub"
},
{
"type": "warning",
"message": "Task 0fcd5716 is more than 200 miles (321 KM) away from any hub.",
"entityType": "task",
"entityId": "ZSfzR90IeDJrjxWBLHbboOjA",
"shortId": "0fcd5716",
"reason": "too-far-from-hub"
}
],
"summary": {
"workers": {
"count": 0
},
"tasks": {
"count": 4,
"cost": 0.4
},
"routeZones": {
"count": 0
},
"vehicles": {
"bicycle": 0,
"car": 1,
"motorcycle": 0,
"truck": 0,
"walking": 0
},
"total": 0.4
},
"shortId": "ae9667659200dbfe"
}