Skip to main content
POST
Assign or Reassign a Route
Use this endpoint to set (or change) who fulfills a route. You can target any of these:
  • Provider (providerId) — an external delivery provider (e.g. uber). Selects the route’s successful quote for that provider.
  • Driver group (driverGroupId) — a contract. Selects the route’s successful quote for that contract.
  • Courier (courierId) — an individual driver. Must belong to the route’s driver group.
  • Vehicle (vehicleId) — a vehicle. Must be assigned to the route’s driver group (contract).
driverGroupId, courierId, and vehicleId accept either an internal Nash id or your own external id. Provide at least one target; you may combine a courier and a vehicle.

Pre-dispatch vs. post-dispatch

The endpoint behaves differently depending on whether the route has already been dispatched:
  • Pre-dispatch — the route’s assignment is updated in place.
  • Post-dispatch — 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.
In both cases the updated route is returned.

Requirements

  • Provide at least one target (providerId, driverGroupId, courierId, or vehicleId).
  • Assigning by provider or driver group selects that target’s successful quote on the route — a successful quote for it must already exist.
  • A courier must belong to the route’s driver group.
  • A vehicle must be assigned to the route’s driver group (contract).

Errors

Failed assignments return 400 Bad Request with a body of shape { "error": { "code", "message", "details": { "reason" } }, "response_status", "RequestID" }. Common reasons: A request with no target fails validation with 422 Unprocessable Content.
To assign a route using your own identifier instead of the Nash route id, use Assign or Reassign a Route by external id.

Authorizations

Authorization
string
header
required

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

Path Parameters

id
string
required

Route ID

Body

application/json

Input for assigning or reassigning a route.

Provide a provider, a driver group (contract), a courier, and/or a vehicle; driver group / courier / vehicle ids may be internal or external. Pre-dispatch the assignment is updated in place; post-dispatch the route is reassigned (cancel live deliveries, recreate tasks, re-quote) and the new target applied.

providerId
string | null

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

Example:

"uber"

driverGroupId
string | null

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

Example:

"cntr_7mP3xVt9Nk8sRfWzY2hLbQ"

courierId
string | null

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

Example:

"cor_9dK2mNp7xVt3RfWzY8sLbQ"

vehicleId
string | null

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

Example:

"veh_4hL8pXq2sVn6RtY3wCbD9M"

Response

OK

Represents a planned sequence of stops for a delivery or batch.

id
string
required

Unique identifier for the route.

Example:

"rte_JphRWDiEosGpXuxwgaYfY3"

portalUrl
string
required

Portal URL of the route.

Example:

"https://portal.usenash.com/routes/rte_JphRWDiEosGpXuxwgaYfY3"

type
string
required

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

Example:

"SINGLE_PICKUP_MULTIPLE_DROPOFFS"

stops
RouteStopSerializer · object[]
required

Ordered list of stops included in the route.

externalId
string | null

External Route ID.

Example:

"rte_JphRWDiEosGpXuxwgaYfY3"

name
string | null

Name of the route.

Example:

"Route 1"

courierId
string | null

Courier ID of the driver assigned to the route.

Example:

"cor_9dK2mNp7xVt3RfWzY8sLbQ"

vehicleId
string | null

Vehicle ID of the vehicle assigned to the route.

Example:

"veh_4hL8pXq2sVn6RtY3wCbD9M"

courier
CourierSerializer · object | null

Courier/driver details for the route.

driverGroup
DriverGroupSerializer · object | null

Driver group assigned to the route.

courierPosition
CourierPositionSerializer · object | null

Current GPS position of the assigned courier.

vehicle
VehicleSerializer · object | null

Vehicle details for the route.

providerName
string | null

Name of the delivery provider assigned to this route.

shiftId
string | null

Shift ID of the shift assigned to the route.

Example:

"shf_1234567890abcdef12345678"

isDispatched
boolean
default:false

Whether the route is dispatched.

jobId
string | null

Dispatched Job ID of this route

Example:

"job_1234567890abcdef12345678"

routeMetadata
Routemetadata · object | null

Additional metadata for the route.

Example:
validationErrors
Validationerrors · object | null

Validation errors for the route.

Example:
encodedPolyline
string | null

Encoded polyline representing the route geometry.

status
string | null

Current status of the route.

Example:

"CREATED"

statusHistory
Statushistory · object[] | null

History of status changes for the route.

Example: