USusenash
Route

Create or Update Route

Changed on

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

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

Changes

  • e3713837c5c9Revision changes
    • breaking

      response property route/statusHistory/anyOf[subschema #1]/items/additionalProperties/ list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property route/stops/items/distanceFromPrevious list-of-types was widened by adding types integer to media type application/json of response 200

    • breaking

      response property route/stops/items/durationFromPrevious list-of-types was widened by adding types integer to media type application/json of response 200

    • breaking

      response property route/stops/items/serviceTime list-of-types was widened by adding types integer to media type application/json of response 200

    • info

      added the optional property //////////// to the response with the status