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 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, 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 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.
• 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.

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

Where to go next

• Create or update a route with an optimized plan.
• List routes by date or retrieve a specific route by name.