> ## Documentation Index
> Fetch the complete documentation index at: https://detrack.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Routes: Multi-stop delivery plans for Detrack drivers

> A Route assigns jobs to drivers with an optimized sequence, start depot, and time window. Learn how Detrack computes and returns routes.

A **Route** is a planned sequence of [jobs](/concepts/jobs) assigned to one or more drivers for a specific date. When you create a route, Detrack computes an optimized job sequence starting from a [depot](/concepts/depots), respecting time windows and vehicle constraints.

## Fields

* `name` (string, required) — A label for the route, for example "Morning Route".
* `date` (date, required) — Route date in `YYYY-MM-DD`.
* `vehicles` (array of strings, required) — Driver names to include in the route.
* `job_ids` (array of strings, required) — Detrack job IDs to plan.
* `depot_location` (object) — Starting depot. Required when `manual_depot` is `true`. Either `{ "id": "..." }` for a saved depot, or `{ "name": "...", "address": "..." }`, which saves or updates a depot with that name.
* `end_depot_location` (object) — Optional ending depot in the same format.
* `mode` (string) — Transport mode: `drive`, `light_truck`, `medium_truck`, `truck`, or `heavy_truck`. Default `drive`.
* `manual_time_windows` (boolean) — Set to `true` to use `time_window_from` and `time_window_to` for the whole plan. Default `false`, which uses each vehicle's own working hours.
* `time_window_from`, `time_window_to` (string) — Plan time window in 24-hour `HH:MM`. Only used, and then required, when `manual_time_windows` is `true`.
* `traffic` (string) — Traffic model for the routing engine: `free_flow` (default) or `approximated`.
* `max_speed` (number) — Maximum vehicle speed in your account's distance unit: km/h if the account uses kilometres, mph if it uses miles.
* `service_time` (integer) — Average service time per stop in minutes.
* `manual_service_time` (boolean) — Apply a fixed service time to every stop.
* `avoid_toll` (boolean) — Skip toll roads. Default `false`.

## Result

A route response has two levels:

* **The plan** (top level): `status`, `depot_location`, `total_distance` (meters), `total_time` (seconds), `total_planned`, `total_unplanned`, and `unplanned_jobs` (jobs that couldn't be placed on any vehicle).
* **`planned_routes`**: one entry per vehicle, each with its own `status`, `vehicle`, `start_time`, `completion_time`, time window, totals, and `planned_jobs` in delivery order with `job_sequence` and `eta_time`.

While Detrack is still optimizing, the plan has a `jobs` array instead of `planned_routes`.

## Route status

Route status describes the route plan, not the jobs in it. It's separate from a job's `status` and `tracking_status`. A route response has two levels of status:

* The top-level `status` is for the plan as a whole.
* Each entry in `planned_routes` (one per vehicle) has its own `status`.

### Plan status

| Status | Meaning |
| - | - |
| `new`, `routing_in_progress` | Detrack is still optimizing the plan. [Plan route](/api-reference/routes/plan) returns `202 Accepted` in this state. |
| `to_be_confirm` | Optimization finished and every job was placed. |
| `routing_completed` | Optimization finished for a large plan that Detrack processed in batches. |
| `routing_failed` | Some jobs couldn't be placed (see `unplanned_jobs`), or optimization failed. |

### Vehicle route status

| Status | Meaning |
| - | - |
| `to_be_confirm` | The route is planned, but its jobs haven't been assigned. This is the result when `assign_route` is `false`. |
| `route_assigned` | The route's jobs were assigned to the vehicle's driver (`assign_route` is `true`). |
| `route_assigned_without_driver` | The route's jobs got their sequence, ETA, and run number, but no driver (`assign_route` and `vrp_exclude_send_driver` are both `true`). |
| `unplanned_jobs` | A holding route for jobs that couldn't be placed on any vehicle. |

### How planning affects jobs

Planning a route only changes jobs when you set `assign_route` to `true`:

* **`assign_route` is `false` (default):** the jobs aren't changed. Their `status`, driver, and `tracking_status` stay the same.
* **`assign_route` is `true`:** each planned job that isn't already `completed`, `completed_partial`, or `failed` gets the route's driver, its sequence (`job_order`), `eta_time`, and run number. Its `status` is set to `dispatched` (or `out_for_delivery` for accounts in courier mode), so its `tracking_status` changes to "Scheduled" or "Out for delivery" depending on the job date. See [Status fields](/concepts/jobs#status-fields).
* **`assign_route` and `vrp_exclude_send_driver` are both `true`:** jobs get their sequence, ETA, and run number, but no driver, and their `status` doesn't change.

<Note>
  Vehicle working hours (`start_time` / `end_time`) are configured per driver in the Detrack app, not in the route payload.
</Note>

## Where to go next

* [Create or update a route](/api-reference/routes/plan) with an optimized plan.
* [List routes by date](/api-reference/routes/list) or [retrieve a specific route by name](/api-reference/routes/retrieve).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.