Sign in
latestOpenAPI 3.1.02026-07-2296226496.3 KB

09a23a95889b

Route

Assign or Reassign a Route

Assign a route to a provider, driver group (contract), courier, or vehicle. Driver group / courier / vehicle accept an internal or external id. Pre-dispatch the assignment is updated in place. Post-dispatch the route is reassigned — the active assignment is cancelled, live deliveries are cancelled, tasks are recreated and re-quoted, a fresh route assignment is created, and the requested target is applied. Returns the updated route.

post/v1/routes/{id}/assign

Path parameters

idstring required

Route ID

Route ID

Request body

providerIdstring nullable

Provider id to assign. Selects the route's successful quote for this provider.

driverGroupIdstring nullable

Driver group/Contract id (internal or external) to assign. Selects the route's successful quote for this contract.

courierIdstring nullable

Courier/Driver id (internal or external) to assign to the route. The courier must belong to the route's driver group.

vehicleIdstring nullable

Vehicle id (internal or external) to assign to the route. The vehicle must be assigned to the route's driver group (contract).

Example request

{
  "providerId": "uber",
  "driverGroupId": "cntr_7mP3xVt9Nk8sRfWzY2hLbQ",
  "courierId": "cor_9dK2mNp7xVt3RfWzY8sLbQ",
  "vehicleId": "veh_4hL8pXq2sVn6RtY3wCbD9M"
}

Response

OK

idstring required

Unique identifier for the route.

externalIdstring nullable

External Route ID.

portalUrlstring required

Portal URL of the route.

namestring nullable

Name of the route.

typestring required

Type of the route, indicating the pickup/dropoff structure.

courierIdstring nullable

Courier ID of the driver assigned to the route.

vehicleIdstring nullable

Vehicle ID of the vehicle assigned to the route.

providerNamestring nullable

Name of the delivery provider assigned to this route.

shiftIdstring nullable

Shift ID of the shift assigned to the route.

isDispatchedboolean

Whether the route is dispatched.

jobIdstring nullable

Dispatched Job ID of this route

routeMetadataobject nullable

Additional metadata for the route.

validationErrorsobject nullable

Validation errors for the route.

encodedPolylinestring nullable

Encoded polyline representing the route geometry.

statusstring nullable

Current status of the route.

statusHistoryobject[] nullable

History of status changes for the route.

Example response

{
  "id": "rte_JphRWDiEosGpXuxwgaYfY3",
  "externalId": "rte_JphRWDiEosGpXuxwgaYfY3",
  "portalUrl": "https://portal.usenash.com/routes/rte_JphRWDiEosGpXuxwgaYfY3",
  "name": "Route 1",
  "type": "SINGLE_PICKUP_MULTIPLE_DROPOFFS",
  "courierId": "cor_9dK2mNp7xVt3RfWzY8sLbQ",
  "vehicleId": "veh_4hL8pXq2sVn6RtY3wCbD9M",
  "shiftId": "shf_1234567890abcdef12345678",
  "stops": [
    {
      "stopType": "PICKUP",
      "objectIds": [
        "ord_Qr5bVt8WiByGh66z2g7xEu",
        "ord_WJFuooSiRvFCaceGZjpbqs"
      ],
      "arrivalTime": "2025-04-25T03:27:00",
      "departTime": "2025-04-25T03:30:00",
      "plannedArrivalTime": "2025-04-25T03:27:00",
      "serviceTime": 360,
      "distanceFromPrevious": 3376,
      "durationFromPrevious": 420,
      "location": {
        "lat": 45.558214,
        "lng": -122.587074
      },
      "status": "PENDING",
      "statusDescription": "leave_unattended",
      "statusHistory": [
        {
          "created_at": "2025-04-25T03:00:00Z",
          "status": "PENDING"
        },
        {
          "created_at": "2025-04-25T03:15:00Z",
          "status": "ENROUTE"
        },
        {
          "created_at": "2025-04-25T03:20:00Z",
          "status": "COMPLETED",
          "status_description": "leave_unattended"
        }
      ],
      "startedAt": "2025-04-25T03:27:00Z",
      "orders": [
        {
          "id": "ord_Qr5bVt8WiByGh66z2g7xEu",
          "orderItems": [
            {
              "id": "item-001",
              "status": "delivered",
              "statusMetadata": {
                "failureLocation": "dropoff"
              },
              "statusHistory": [
                {
                  "status": "picked",
                  "createdAt": "2025-04-25T03:20:00"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "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"
    }
  ]
}