Assign or Reassign a Route by external id

curl --request POST \
  --url https://api.sandbox.usenash.com/v1/routes/external-identifier/{external_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/external-identifier/{external_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/external-identifier/{external_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/external-identifier/{external_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/external-identifier/{external_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/external-identifier/{external_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/external-identifier/{external_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>"
  }
]

POST

routes

external-identifier

{external_id}

assign

Assign or Reassign a Route by external id

curl --request POST \
  --url https://api.sandbox.usenash.com/v1/routes/external-identifier/{external_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/external-identifier/{external_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/external-identifier/{external_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/external-identifier/{external_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/external-identifier/{external_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/external-identifier/{external_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/external-identifier/{external_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>"
  }
]

Identical to Assign or Reassign a Route, except the route is identified by the external id you supplied when creating it rather than the Nash route id. See that page for the full assignment behavior (targets, and pre- vs. post-dispatch handling).

Authorizations

Authorization

string

header

required

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

Path Parameters

externalId

string

required

External identifier of the route

Example:

"rte_ext_123"

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

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

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.

Show child attributes

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.

Show child attributes

driverGroup

DriverGroupSerializer · object | null

Driver group assigned to the route.

Show child attributes

courierPosition

CourierPositionSerializer · object | null

Current GPS position of the assigned courier.

Show child attributes

vehicle

VehicleSerializer · object | null

Vehicle details for the route.

Show child attributes

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:

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

validationErrors

Validationerrors · object | null

Validation errors for the route.

Show child attributes

Example:

{
  "order_123": "Order 123 has pickup but no dropoff"
}

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.

Show child attributes

Example:

[
  {
    "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"
  }
]

Getting started

Order

Dispatch strategies

Notifications

Store locations & zones

Jobs

Batch jobs

Providers

Routes

Optimization strategies

Shifts

Templates

Store catalog

Feedback

Shipping

Simulate delivery

Fleet

Miscellaneous

Assign or Reassign a Route by external id

Authorizations

Path Parameters

Body

Response