Sign in

v1

latestOpenAPI 3.1.02026-07-2296226496.3 KB
Route

Create or Update Route

Create a new route or update an existing one. A route defines an optimized sequence of stops with orders assigned to each stop.

post/v1/routes

Request body

externalIdstring nullable

Route ID. If provided, the route will be updated. If not provided, a new route will be created.

namestring nullable

Name of the route.

routeMetadataobject nullable

Additional metadata for the route.

vehicleIdstring nullable

Vehicle ID (or external ID) to assign to this route.

courierIdstring nullable

Courier/Driver ID (or external ID) to assign to this route.

driverGroupIdstring nullable

Driver group/Contract ID (or external ID) to assign to this route. Required when assigning a courier or vehicle.

autoDispatchboolean

If true, dispatch the route to providers in the same request after upsert. Default: false.

Example request

{
  "externalId": "rte_JphRWDiEosGpXuxwgaYfY3",
  "name": "Route 1",
  "stops": [
    {
      "arrival_time": "2025-04-25T08:00:00Z",
      "depart_time": "2025-04-25T08:00:00Z",
      "location": {
        "lat": 40.7128,
        "lng": -74.006
      },
      "object_ids": [
        "stl_warehouse_123"
      ],
      "service_time": 0,
      "stop_type": "ROUTE_START"
    },
    {
      "distance_from_previous": 5000,
      "duration_from_previous": 1200,
      "location": {
        "lat": 40.7589,
        "lng": -73.9851
      },
      "object_ids": [
        "ord_123",
        "ord_456"
      ],
      "service_time": 600,
      "stop_type": "PICKUP"
    },
    {
      "arrival_time": "2025-04-25T10:00:00Z",
      "depart_time": "2025-04-25T10:30:00Z",
      "object_ids": [
        "break_001"
      ],
      "service_time": 1800,
      "stop_type": "DRIVER_BREAK"
    },
    {
      "distance_from_previous": 2000,
      "duration_from_previous": 600,
      "location": {
        "lat": 40.7505,
        "lng": -73.9934
      },
      "object_ids": [
        "ord_123"
      ],
      "service_time": 180,
      "stop_type": "DROPOFF"
    }
  ],
  "routeMetadata": {
    "priority": "high",
    "source": "optimization_engine"
  },
  "vehicleId": "veh_4hL8pXq2sVn6RtY3wCbD9M",
  "courierId": "cor_9dK2mNp7xVt3RfWzY8sLbQ",
  "driverGroupId": "cntr_7mP3xVt9Nk8sRfWzY2hLbQ"
}

Response

OK