curl --request POST \
--url https://api.sandbox.usenash.com/v1/routes/{id}/assign \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"providerId": "uber",
"driverGroupId": "cntr_7mP3xVt9Nk8sRfWzY2hLbQ",
"courierId": "cor_9dK2mNp7xVt3RfWzY8sLbQ",
"vehicleId": "veh_4hL8pXq2sVn6RtY3wCbD9M"
}
'import requests
url = "https://api.sandbox.usenash.com/v1/routes/{id}/assign"
payload = {
"providerId": "uber",
"driverGroupId": "cntr_7mP3xVt9Nk8sRfWzY2hLbQ",
"courierId": "cor_9dK2mNp7xVt3RfWzY8sLbQ",
"vehicleId": "veh_4hL8pXq2sVn6RtY3wCbD9M"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
providerId: 'uber',
driverGroupId: 'cntr_7mP3xVt9Nk8sRfWzY2hLbQ',
courierId: 'cor_9dK2mNp7xVt3RfWzY8sLbQ',
vehicleId: 'veh_4hL8pXq2sVn6RtY3wCbD9M'
})
};
fetch('https://api.sandbox.usenash.com/v1/routes/{id}/assign', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.usenash.com/v1/routes/{id}/assign",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'providerId' => 'uber',
'driverGroupId' => 'cntr_7mP3xVt9Nk8sRfWzY2hLbQ',
'courierId' => 'cor_9dK2mNp7xVt3RfWzY8sLbQ',
'vehicleId' => 'veh_4hL8pXq2sVn6RtY3wCbD9M'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.usenash.com/v1/routes/{id}/assign"
payload := strings.NewReader("{\n \"providerId\": \"uber\",\n \"driverGroupId\": \"cntr_7mP3xVt9Nk8sRfWzY2hLbQ\",\n \"courierId\": \"cor_9dK2mNp7xVt3RfWzY8sLbQ\",\n \"vehicleId\": \"veh_4hL8pXq2sVn6RtY3wCbD9M\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.usenash.com/v1/routes/{id}/assign")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"providerId\": \"uber\",\n \"driverGroupId\": \"cntr_7mP3xVt9Nk8sRfWzY2hLbQ\",\n \"courierId\": \"cor_9dK2mNp7xVt3RfWzY8sLbQ\",\n \"vehicleId\": \"veh_4hL8pXq2sVn6RtY3wCbD9M\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.usenash.com/v1/routes/{id}/assign")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"providerId\": \"uber\",\n \"driverGroupId\": \"cntr_7mP3xVt9Nk8sRfWzY2hLbQ\",\n \"courierId\": \"cor_9dK2mNp7xVt3RfWzY8sLbQ\",\n \"vehicleId\": \"veh_4hL8pXq2sVn6RtY3wCbD9M\"\n}"
response = http.request(request)
puts response.read_body{
"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",
"plannedArrivalTime": "2025-04-25T03:27:00",
"serviceTime": 360,
"distanceFromPrevious": 3376,
"durationFromPrevious": 420,
"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"
}
],
"metadata": {},
"startedAt": "2025-04-25T03:27:00Z",
"breakDuration": 123,
"orders": [
{
"id": "ord_Qr5bVt8WiByGh66z2g7xEu",
"externalId": "<string>",
"publicTrackingUrl": "<string>",
"pod": [
{
"type": "<string>",
"url": "<string>",
"uploadedAt": "<string>"
}
],
"orderItems": [
{
"id": "item-001",
"description": "<string>",
"count": 123,
"valueCents": 123,
"barcode": "<string>",
"sku": "<string>",
"category": "<string>",
"status": "delivered",
"availableQuantity": 123,
"statusMetadata": {
"pickedAt": "<string>",
"deliveredAt": "<string>",
"failedAt": "<string>",
"returnedAt": "<string>",
"failureReason": "<string>",
"failureLocation": "dropoff"
},
"statusHistory": [
{
"status": "picked",
"createdAt": "2025-04-25T03:20:00"
}
],
"subItems": [
"<unknown>"
]
}
]
}
]
}
],
"externalId": "rte_JphRWDiEosGpXuxwgaYfY3",
"name": "Route 1",
"courierId": "cor_9dK2mNp7xVt3RfWzY8sLbQ",
"vehicleId": "veh_4hL8pXq2sVn6RtY3wCbD9M",
"courier": {
"id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"phoneNumber": "<string>"
},
"driverGroup": {
"id": "<string>",
"externalId": "<string>"
},
"courierPosition": {
"lat": 123,
"lng": 123,
"updatedAt": "<string>",
"capturedAt": "<string>",
"accuracy": 123,
"heading": 123,
"speed": 123,
"altitude": 123,
"altitudeAccuracy": 123,
"batteryLevel": 123,
"batteryIsCharging": true,
"isMoving": true
},
"vehicle": {
"licensePlate": "<string>",
"make": "<string>",
"model": "<string>",
"color": "<string>",
"year": 123,
"type": "<string>"
},
"providerName": "<string>",
"shiftId": "shf_1234567890abcdef12345678",
"isDispatched": false,
"jobId": "job_1234567890abcdef12345678",
"routeMetadata": {
"priority": "high",
"source": "optimization_engine"
},
"validationErrors": {
"order_123": "Order 123 has pickup but no dropoff"
},
"encodedPolyline": "<string>",
"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"
}
]
}[
{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"response_status": "<string>",
"RequestID": "<string>"
}
]Assign or Reassign a Route
Assign a route to a provider, driver group, courier, or vehicle — before or after dispatch.
curl --request POST \
--url https://api.sandbox.usenash.com/v1/routes/{id}/assign \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"providerId": "uber",
"driverGroupId": "cntr_7mP3xVt9Nk8sRfWzY2hLbQ",
"courierId": "cor_9dK2mNp7xVt3RfWzY8sLbQ",
"vehicleId": "veh_4hL8pXq2sVn6RtY3wCbD9M"
}
'import requests
url = "https://api.sandbox.usenash.com/v1/routes/{id}/assign"
payload = {
"providerId": "uber",
"driverGroupId": "cntr_7mP3xVt9Nk8sRfWzY2hLbQ",
"courierId": "cor_9dK2mNp7xVt3RfWzY8sLbQ",
"vehicleId": "veh_4hL8pXq2sVn6RtY3wCbD9M"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
providerId: 'uber',
driverGroupId: 'cntr_7mP3xVt9Nk8sRfWzY2hLbQ',
courierId: 'cor_9dK2mNp7xVt3RfWzY8sLbQ',
vehicleId: 'veh_4hL8pXq2sVn6RtY3wCbD9M'
})
};
fetch('https://api.sandbox.usenash.com/v1/routes/{id}/assign', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.usenash.com/v1/routes/{id}/assign",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'providerId' => 'uber',
'driverGroupId' => 'cntr_7mP3xVt9Nk8sRfWzY2hLbQ',
'courierId' => 'cor_9dK2mNp7xVt3RfWzY8sLbQ',
'vehicleId' => 'veh_4hL8pXq2sVn6RtY3wCbD9M'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.usenash.com/v1/routes/{id}/assign"
payload := strings.NewReader("{\n \"providerId\": \"uber\",\n \"driverGroupId\": \"cntr_7mP3xVt9Nk8sRfWzY2hLbQ\",\n \"courierId\": \"cor_9dK2mNp7xVt3RfWzY8sLbQ\",\n \"vehicleId\": \"veh_4hL8pXq2sVn6RtY3wCbD9M\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.usenash.com/v1/routes/{id}/assign")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"providerId\": \"uber\",\n \"driverGroupId\": \"cntr_7mP3xVt9Nk8sRfWzY2hLbQ\",\n \"courierId\": \"cor_9dK2mNp7xVt3RfWzY8sLbQ\",\n \"vehicleId\": \"veh_4hL8pXq2sVn6RtY3wCbD9M\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.usenash.com/v1/routes/{id}/assign")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"providerId\": \"uber\",\n \"driverGroupId\": \"cntr_7mP3xVt9Nk8sRfWzY2hLbQ\",\n \"courierId\": \"cor_9dK2mNp7xVt3RfWzY8sLbQ\",\n \"vehicleId\": \"veh_4hL8pXq2sVn6RtY3wCbD9M\"\n}"
response = http.request(request)
puts response.read_body{
"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",
"plannedArrivalTime": "2025-04-25T03:27:00",
"serviceTime": 360,
"distanceFromPrevious": 3376,
"durationFromPrevious": 420,
"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"
}
],
"metadata": {},
"startedAt": "2025-04-25T03:27:00Z",
"breakDuration": 123,
"orders": [
{
"id": "ord_Qr5bVt8WiByGh66z2g7xEu",
"externalId": "<string>",
"publicTrackingUrl": "<string>",
"pod": [
{
"type": "<string>",
"url": "<string>",
"uploadedAt": "<string>"
}
],
"orderItems": [
{
"id": "item-001",
"description": "<string>",
"count": 123,
"valueCents": 123,
"barcode": "<string>",
"sku": "<string>",
"category": "<string>",
"status": "delivered",
"availableQuantity": 123,
"statusMetadata": {
"pickedAt": "<string>",
"deliveredAt": "<string>",
"failedAt": "<string>",
"returnedAt": "<string>",
"failureReason": "<string>",
"failureLocation": "dropoff"
},
"statusHistory": [
{
"status": "picked",
"createdAt": "2025-04-25T03:20:00"
}
],
"subItems": [
"<unknown>"
]
}
]
}
]
}
],
"externalId": "rte_JphRWDiEosGpXuxwgaYfY3",
"name": "Route 1",
"courierId": "cor_9dK2mNp7xVt3RfWzY8sLbQ",
"vehicleId": "veh_4hL8pXq2sVn6RtY3wCbD9M",
"courier": {
"id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"phoneNumber": "<string>"
},
"driverGroup": {
"id": "<string>",
"externalId": "<string>"
},
"courierPosition": {
"lat": 123,
"lng": 123,
"updatedAt": "<string>",
"capturedAt": "<string>",
"accuracy": 123,
"heading": 123,
"speed": 123,
"altitude": 123,
"altitudeAccuracy": 123,
"batteryLevel": 123,
"batteryIsCharging": true,
"isMoving": true
},
"vehicle": {
"licensePlate": "<string>",
"make": "<string>",
"model": "<string>",
"color": "<string>",
"year": 123,
"type": "<string>"
},
"providerName": "<string>",
"shiftId": "shf_1234567890abcdef12345678",
"isDispatched": false,
"jobId": "job_1234567890abcdef12345678",
"routeMetadata": {
"priority": "high",
"source": "optimization_engine"
},
"validationErrors": {
"order_123": "Order 123 has pickup but no dropoff"
},
"encodedPolyline": "<string>",
"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"
}
]
}[
{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"response_status": "<string>",
"RequestID": "<string>"
}
]- 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.
Requirements
- Provide at least one target (
providerId,driverGroupId,courierId, orvehicleId). - 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 return400 Bad Request with a body of shape { "error": { "code", "message", "details": { "reason" } }, "response_status", "RequestID" }. Common reasons:
reason | Meaning |
|---|---|
courier_not_assigned_to_driver_group | The courier isn’t a member of the route’s driver group. Move the route to a group the courier belongs to, or add the courier to that group. |
vehicle_not_assigned_to_contract | The vehicle isn’t assigned to the route’s driver group (contract). |
422 Unprocessable Content.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Route ID
Body
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.
Provider id to assign. Selects the route's successful quote for this provider.
"uber"
Driver group/Contract id (internal or external) to assign. Selects the route's successful quote for this contract.
"cntr_7mP3xVt9Nk8sRfWzY2hLbQ"
Courier/Driver id (internal or external) to assign to the route. The courier must belong to the route's driver group.
"cor_9dK2mNp7xVt3RfWzY8sLbQ"
Vehicle id (internal or external) to assign to the route. The vehicle must be assigned to the route's driver group (contract).
"veh_4hL8pXq2sVn6RtY3wCbD9M"
Response
OK
Represents a planned sequence of stops for a delivery or batch.
Unique identifier for the route.
"rte_JphRWDiEosGpXuxwgaYfY3"
Portal URL of the route.
"https://portal.usenash.com/routes/rte_JphRWDiEosGpXuxwgaYfY3"
Type of the route, indicating the pickup/dropoff structure.
"SINGLE_PICKUP_MULTIPLE_DROPOFFS"
Ordered list of stops included in the route.
Show child attributes
Show child attributes
External Route ID.
"rte_JphRWDiEosGpXuxwgaYfY3"
Name of the route.
"Route 1"
Courier ID of the driver assigned to the route.
"cor_9dK2mNp7xVt3RfWzY8sLbQ"
Vehicle ID of the vehicle assigned to the route.
"veh_4hL8pXq2sVn6RtY3wCbD9M"
Courier/driver details for the route.
Show child attributes
Show child attributes
Driver group assigned to the route.
Show child attributes
Show child attributes
Current GPS position of the assigned courier.
Show child attributes
Show child attributes
Vehicle details for the route.
Show child attributes
Show child attributes
Name of the delivery provider assigned to this route.
Shift ID of the shift assigned to the route.
"shf_1234567890abcdef12345678"
Whether the route is dispatched.
Dispatched Job ID of this route
"job_1234567890abcdef12345678"
Additional metadata for the route.
{
"priority": "high",
"source": "optimization_engine"
}
Validation errors for the route.
Show child attributes
Show child attributes
{
"order_123": "Order 123 has pickup but no dropoff"
}
Encoded polyline representing the route geometry.
Current status of the route.
"CREATED"
History of status changes for the route.
Show child attributes
Show child attributes
[
{
"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"
}
]
Was this page helpful?