Skip to main content
POST
/
v1
/
routes
Create or Update Route
curl --request POST \
  --url https://api.sandbox.usenash.com/v1/routes \
  --header 'Content-Type: application/json' \
  --data '{
  "externalId": "rte_JphRWDiEosGpXuxwgaYfY3",
  "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"
  }
}'
{
  "route": {
    "id": "rte_JphRWDiEosGpXuxwgaYfY3",
    "externalId": "rte_JphRWDiEosGpXuxwgaYfY3",
    "type": "SINGLE_PICKUP_MULTIPLE_DROPOFFS",
    "stops": [
      {
        "stopType": "PICKUP",
        "objectIds": [
          "ord_Qr5bVt8WiByGh66z2g7xEu",
          "ord_WJFuooSiRvFCaceGZjpbqs"
        ],
        "arrivalTime": "2025-04-25T03:27:00",
        "departTime": "2025-04-25T03:30:00",
        "serviceTime": 360,
        "distanceFromPrevious": 3376,
        "durationFromPrevious": 420,
        "location": {
          "lat": 45.558214,
          "lng": -122.587074
        }
      }
    ],
    "jobId": "job_1234567890abcdef12345678",
    "routeMetadata": {
      "priority": "high",
      "source": "optimization_engine"
    }
  }
}
A Route object represents a planned sequence of stops for a vehicle or delivery agent. The core of the Route is the stops array, which lists the specific locations to visit in order. Each stop within this array details:
  • The actions to be performed (like stopType).
  • Associated items (objectIds).
  • Timing estimates (arrivalTime, departTime, serviceTime).
  • Travel details from the prior stop (distanceFromPrevious, durationFromPrevious).
  • The physical coordinates (location).
This endpoint allows you to create a new route or update an existing one by providing route configuration and stop details.

Body

application/json

Input for creating or updating a route.

​
externalId
string | null

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

Example:

"rte_JphRWDiEosGpXuxwgaYfY3"

​
stops
RouteStopInputSerializer · object[] | null

Complete route stops structure with timing, location, and stop types. Supports all stop types including PICKUP, DROPOFF, ROUTE_START, ROUTE_END, and DRIVER_BREAK.

Example:
[
  {
    "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
object | null

Additional metadata for the route.

Example:
{
  "priority": "high",
  "source": "optimization_engine"
}

Response

OK

Response for route upsert operation.

​
route
object
required

The created or updated route.

⌘I