Skip to main content
POST
/
v1
/
routes
Create or Update Route
curl --request POST \
  --url https://api.sandbox.usenash.com/v1/routes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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": "vhc_1234567890abcdef12345678",
  "courierId": "cou_1234567890abcdef12345678"
}
'
{
  "route": {
    "id": "rte_JphRWDiEosGpXuxwgaYfY3",
    "portalUrl": "https://portal.usenash.com/routes/rte_JphRWDiEosGpXuxwgaYfY3",
    "type": "SINGLE_PICKUP_MULTIPLE_DROPOFFS",
    "stops": [
      {
        "stopType": "PICKUP",
        "objectIds": [
          "ord_Qr5bVt8WiByGh66z2g7xEu",
          "ord_WJFuooSiRvFCaceGZjpbqs"
        ],
        "location": {
          "lat": 45.558214,
          "lng": -122.587074
        },
        "arrivalTime": "2025-04-25T03:27:00",
        "departTime": "2025-04-25T03:30:00",
        "serviceTime": 360,
        "distanceFromPrevious": 3376,
        "durationFromPrevious": 420,
        "status": "PENDING",
        "statusHistory": [
          {
            "created_at": "2025-04-25T03:00:00Z",
            "status": "PENDING"
          },
          {
            "created_at": "2025-04-25T03:15:00Z",
            "status": "ENROUTE"
          }
        ]
      }
    ],
    "externalId": "rte_JphRWDiEosGpXuxwgaYfY3",
    "name": "Route 1",
    "courierId": "cou_1234567890abcdef12345678",
    "vehicleId": "vhc_1234567890abcdef12345678",
    "shiftId": "shf_1234567890abcdef12345678",
    "jobId": "job_1234567890abcdef12345678",
    "routeMetadata": {
      "priority": "high",
      "source": "optimization_engine"
    },
    "validationErrors": {
      "order_123": "Order 123 has pickup but no dropoff"
    },
    "status": "CREATED",
    "statusHistory": [
      {
        "created_at": "2025-04-25T03:00:00Z",
        "status": "CREATED"
      },
      {
        "created_at": "2025-04-25T03:10:00Z",
        "status": "ASSIGNED"
      },
      {
        "created_at": "2025-04-25T03:15:00Z",
        "status": "STARTED"
      }
    ]
  }
}
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.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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"

​
name
string | null

Name of the route.

Example:

"Route 1"

​
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
Routemetadata · object

Additional metadata for the route.

Example:
{
  "priority": "high",
  "source": "optimization_engine"
}
​
vehicleId
string | null

Vehicle ID to assign to this route.

Example:

"vhc_1234567890abcdef12345678"

​
courierId
string | null

Courier/Driver ID to assign to this route.

Example:

"cou_1234567890abcdef12345678"

Response

OK

Response for route upsert operation.

​
route
RouteSerializer · object
required

The created or updated route.