Requires the v3 Route Optimization Engine (available in Scale and Enterprise plans only). Contact your customer success representative or support@onfleet.com for more information.

This use of the route optimization endpoint initializes a route optimization workflow that intelligently inserts selected “on-demand” tasks into workers’ (drivers’) existing routes.
It requires information about the route optimization (RO) as request parameters, plus an extra parameter, jobType, and responds with issues. If successful, it provides a summary and an ID for the next step in the optimization process.

Name	Type	Description
jobType	String	The only acceptable value here is `ON-DEMAND`.

The following fields are the same ones from Initialize Standard Route Optimization

Name	Type	Description
autoApplyAssignment	Boolean	Optional. We recommend this value to set to true for the ON-DEMAND usage. When set to `true`, assignments will be automatically applied immediately after the Route Optimization engine processes them, without the need to call the subsequent Apply Optimization Results request URL. The default value is `false`. You will still need to call Start Route Optimization.
tasks	Array of Strings	Required. The list of tasks ID(s)s that are unassigned to consider for the Route Optimization.
teams	Object	Required. The Team IDs and their associated workers' ID for Route Optimization to consider.
date	Number	Required. Unix timestamp in millisecond precision.
timezone	String	Required. The timezone in which the optimization should consider.
mode	Number	Required. 0 for Minimize Distance Driven. 1 for Always on Time. 2 for Aggressive batch order pairs(use for linked Tasks). 3 for Balance Driving distance and Timely Arrival
serviceTime	Number	Required. The time that should be spent by the workers at each Task location, in minutes.
maxViolationTime	Number	Required. Max allowed delay time, in minutes
maxTasksPerRoute	Number	Required. The maximum number of tasks a worker can be assigned.
schedulingMethod	Number	Required. Schedules that the RO should consider. 1 for use default schedule. 2 for worker schedules only.
defaultSchedule	Array of Numbers	Required. An array of default schedules if no specific worker schedule is available.
defaultScheduleTimestamps	Array of Numbers	If provided, will overwrite `defaultSchedule`. Supply as one or more sets of Unix timestamps in millisecond precision. Here is a minimal example: `[ [ 1754424607048, 1754428207048 ] ]`
optimizationServiceArea	String	Optional. The ID of the optimization service area if applicable.
routeStart	String	Required, see below. Starting point of the route, can be a hub or a worker's Location.
routeEnd	String	Required, see below. Ending point of the route.
osaRouteZoneCount	Number	Optional. Only used if RouteZone is involved.

🚧
Route Start and Route End
The request must have at least one routeStart or routeEnd fields; they cannot both be omitted. These fields have very specific formats. The allowed values are:

”teams://DEFAULT” (this will be the team hub)

”workers://ROUTING_ADDRESS” (the workers routing address)

”hub://{hub_id}" (specify a hub)

You also must have at least one of the two (routeStart or routeEnd) set. You can have both set, but having both empty will throw a validation error.

{
  "jobType":"ON-DEMAND",
  "maxTasksPerRoute": 30,
  "date": 1718728193838,
  "timezone": "America/Toronto",
  "mode": 1,
  "serviceTime": 15,
  "tasks": [
    "atnk3APxhJrgfx9mgWaRhByQ",
    "4kA7bOH*Kz7K0YA6~NpqWDke"
  ],
  "teams": {
    "5y1jHFp7OBfFU6SekbwwwRfL": [
      "GLlLB2123ABCkXOJAHPklMPZ",
      "~jCf16ZaT07pdtf~oFb~XAH9"
    ]
  },
  "schedulingMethod": 1,
  "routeStart": "teams://DEFAULT",
  "routeEnd": "teams://DEFAULT",
  "maxViolationTime": 0,
  "defaultSchedule": [
    {
      "date": 1718683200000,
      "slots": [
        {
          "start": "0000",
          "end": "2359"
        }
      ],
      "owner": "pOoPktB~Hry706w2JT30rJGi",
      "timezone": "America/Toronto"
    }
  ]
}

Response fields:

id (string). id for the optimization. This property is not included if issues includes an error.
shortId (string). shortId for the optimization.
issues (Array of issues). An issue includes.
- type (string). “warning“ or “error“. Warnings allow the optimization proceed. Errors prevent successful initialization of RO.
- message (string). User friendly message for the issue.
- shortId (string). shortId for the task causing the issue.
- reason (string). Identifier for the issue.
summary. This property is not included if issues includes an error.
- workers:
  - count (number). number of workers included in the optimization.
- tasks:
  - count (number). number of tasks included in the optimization.
- routeZones:
  - count (number). number of routeZones included in the optimization.

{
  "id": "CQ6rFedL7VBL2VjURsGnb1cx",
  "issues": [
    {
      "type": "warning",
      "message": "Task 611552d3 does not have a time range (completeAfter/completeBefore) specified. Add time range for better optimization.",
      "entityType": "task",
      "entityId": "atnk3APxhJrgfx9mgWaRhByQ",
      "shortId": "611552d3",
      "reason": "no-time-range"
    },
    {
      "type": "warning",
      "message": "Task 08607990 does not have a time range (completeAfter/completeBefore) specified. Add time range for better optimization.",
      "entityType": "task",
      "entityId": "4kA7bOH*Kz7K0YA6~NpqWDke",
      "shortId": "08607990",
      "reason": "no-time-range"
    }
  ],
  "summary": {
    "workers": {
      "count": 2
    },
    "tasks": {
      "count": 2,
      "cost": 0.2
    },
    "routeZones": {
      "count": 0
    },
    "total": 0.2
  },
  "shortId": "682589c95927064e"
}

📘
Use Start Route Optimization
This endpoint is simply setting up the parameters and preview the results. The error handling should occur in this step prior to start Route Optimization using Start Route Optimization