Skip to main content
A route represents a planned sequence of stops for a vehicle or delivery agent. Where a single job is one pickup-to-dropoff delivery, a route bundles many stops into one ordered itinerary — the unit you use when a driver completes several deliveries in a single trip.

​
What a route is

The core of a route is its stops array, which lists the locations to visit in order. Each stop details:
  • The kind of stop (stopType)
  • Associated items (objectIds)
  • Timing estimates (arrivalTime, departTime, serviceTime)
  • Travel details from the prior stop (distanceFromPrevious, durationFromPrevious)
  • The physical coordinates (location)
A route also carries travel metrics and the orders associated with each stop. Retrieve a single route — including its stops, travel metrics, and associated orders — with Get Route (GET /v1/routes/{id}). To browse routes, the list endpoint (GET /v1/routes) returns a slim payload suitable for discovery; use the single-route endpoint for full details.

​
Creating & updating routes

Use Create or Update Route (POST /v1/routes) to create a new route or update an existing one by providing the route configuration and its stop details. This is the manual path: you supply the ordered stops yourself. You can recalculate timing for a route with POST /v1/routes/{id}/calculate-timing, which computes per-stop ETAs and a polyline using truck routing, updating each stop’s arrival and departure times and returning the route polyline.
You don’t have to build routes by hand. Route optimization generates routes for you from a set of orders, and can save them as route objects you then dispatch.

​
Dispatching routes

Once a route is planned, dispatch it with Dispatch Routes (POST /v1/routes/dispatch). This creates jobs for each route and assigns them based on your organization’s dispatch strategy. Pass the route IDs to dispatch: 
{
  "routeIds": ["rte_route_id_1", "rte_route_id_2"],
  "autoDispatch": true
}
ParameterTypeRequiredDescription
routeIdsString[]YesThe route IDs to dispatch
autoDispatchBooleanNoAutomatically dispatch to a provider (default: true)
When autoDispatch is true, the resulting jobs are sent to a provider immediately according to your dispatch strategy. Set it to false to create the jobs without dispatching them right away.

​
Routes vs. route optimization

It’s worth separating two related concepts:
  • A route is the data object — a defined, ordered sequence of stops. You can author routes directly via the API.
  • Route optimization is the engine that produces routes. Given a set of orders and your fleet constraints, the optimizer solves the Vehicle Routing Problem (VRP) — balancing capacity, time windows, driver shifts and breaks, vehicle profiles, traffic, and cost — and returns efficient routes.
A typical optimized flow is: submit orders for optimization, poll until it completes, then either dispatch the optimized orders directly or save them as route objects and dispatch those routes. For the full walkthrough, see the Route Optimization guide.

​
Next steps

Create or Update Route

Build or modify a route and its stops.

Get Route

Retrieve a route’s stops, metrics, and orders.

Dispatch Routes

Turn routes into jobs and dispatch them.

Route Optimization

Generate optimized routes from a set of orders.