--- title: "Assign or Reassign a Route by external id" method: POST path: "/v1/routes/external-identifier/{external_id}/assign" tags: ["Route"] --- # Assign or Reassign a Route by external id `POST /v1/routes/external-identifier/{external_id}/assign` ## Request - Base URL: `https://api.sandbox.usenash.com` - URL: `https://api.sandbox.usenash.com/v1/routes/external-identifier/{external_id}/assign` - Auth: none declared 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. ## Path parameters - `externalId` string, required: External identifier of the route ## Request body - AssignRouteInputSerializer: 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, nullable: Provider id to assign. Selects the route's successful quote for this provider. - `driverGroupId` string, nullable: Driver group/Contract id (internal or external) to assign. Selects the route's successful quote for this contract. - `courierId` string, nullable: Courier/Driver id (internal or external) to assign to the route. The courier must belong to the route's driver group. - `vehicleId` string, nullable: Vehicle id (internal or external) to assign to the route. The vehicle must be assigned to the route's driver group (contract). ## Response `200` OK - RouteSerializer: Represents a planned sequence of stops for a delivery or batch. - `id` string, required: Unique identifier for the route. - `externalId` string, nullable: External Route ID. - `portalUrl` string, required: Portal URL of the route. - `name` string, nullable: Name of the route. - `type` string, required: Type of the route, indicating the pickup/dropoff structure. - `courierId` string, nullable: Courier ID of the driver assigned to the route. - `vehicleId` string, nullable: Vehicle ID of the vehicle assigned to the route. - `courier` CourierSerializer: Courier details for a route. - `id` string, nullable - `firstName` string, nullable - `lastName` string, nullable - `phoneNumber` string, nullable - `driverGroup` DriverGroupSerializer: Driver group details for a route. - `id` string, nullable - `externalId` string, nullable - `courierPosition` CourierPositionSerializer: Current GPS position of a courier. - `lat` number, required: Latitude coordinate. - `lng` number, required: Longitude coordinate. - `updatedAt` string, nullable: Timestamp when the position was last updated on the server. - `capturedAt` string, nullable: Timestamp when the GPS position was captured on driver's device. - `accuracy` number, nullable: Estimated horizontal accuracy radius in meters. - `heading` number, nullable: Heading in degrees relative to true north. - `speed` number, nullable: Speed in meters per second. - `altitude` number, nullable: Altitude in meters above sea level. - `altitudeAccuracy` number, nullable: Estimated altitude accuracy in meters. - `batteryLevel` number, nullable: Battery level from 0.0 to 1.0, if provided by device. - `batteryIsCharging` boolean, nullable: Whether the device is currently charging. - `isMoving` boolean, nullable: Whether the device is currently detected as moving. - `vehicle` VehicleSerializer: Vehicle details for a route. - `licensePlate` string, nullable - `make` string, nullable - `model` string, nullable - `color` string, nullable - `year` integer, nullable - `type` string, nullable - `providerName` string, nullable: Name of the delivery provider assigned to this route. - `shiftId` string, nullable: Shift ID of the shift assigned to the route. - `stops` RouteStopSerializer[], required: Ordered list of stops included in the route. - `stopType` string, required: Type of the stop. - `objectIds` string[], required: List of object IDs (e.g., order IDs, store location IDs) associated with this stop. - `arrivalTime` string, nullable: Estimated arrival time at the stop (UTC). - `departTime` string, nullable: Estimated departure time from the stop (UTC). - `plannedArrivalTime` string, nullable: Snapshot of arrival_time captured pre-dispatch (UTC). Mirrors arrival_time while the route is undispatched, then freezes at dispatch — gives consumers the planned ETA at dispatch even after real-time tracking updates arrival_time. - `serviceTime` integer, nullable: Estimated service time spent at the stop (in seconds). - `distanceFromPrevious` integer, nullable: Distance traveled from the previous stop (in meters). - `durationFromPrevious` integer, nullable: Travel duration from the previous stop (in seconds). - `location` LatLngSerializer, required: Latitude/longitude coordinates. - `lat` number, required: Latitude coordinate. - `lng` number, required: Longitude coordinate. - `status` string, nullable: Current status of the stop. - `statusDescription` string, nullable: Detailed description of the current status of the stop. - `statusHistory` object[], nullable: History of status changes for the stop. - `metadata` object, nullable: Additional metadata for this stop. - `startedAt` string, nullable: Timestamp when the stop entered IN_PROGRESS status (UTC). - `breakDuration` integer, nullable: Duration in seconds of the break at this stop (for DRIVER_BREAK stops). - `orders` StopOrderSerializer[], nullable: Orders associated with this stop, including tracking URLs and delivery details. - `id` string, required: Order ID. - `externalId` string, nullable: External identifier for the order. - `publicTrackingUrl` string, nullable: Public tracking URL for the order. - `pod` ProofOfDeliverySerializer[], nullable: Proof of delivery data (photos, signature, etc.) if captured. - `type` string, required: Type of proof of delivery, e.g., 'photo', 'signature', etc. - `url` string, nullable: URL of the proof of delivery document. - `uploadedAt` string, nullable: Timestamp when the proof of delivery was uploaded. - `orderItems` OrderItemSerializer[], nullable: Items with lifecycle status tracking (picked, delivered, failed, etc.). - `id` string, nullable: The merchant ID of the item - `description` string, nullable: The description of the item - `count` integer, nullable: The quantity of the item - `valueCents` integer, nullable: The value of the item in cents - `barcode` string, nullable: Barcode associated with the item - `sku` string, nullable: SKU of the item - `category` string, nullable: The category of the item - `status` string, nullable: Current lifecycle status of the item. - `availableQuantity` integer, nullable: Quantity available after pickup (may differ from count) - `statusMetadata` ItemStatusMetadataSerializer: Operational metadata tracked during item lifecycle in route delivery. - `pickedAt` string, nullable: Timestamp when the item was picked up - `deliveredAt` string, nullable: Timestamp when the item was delivered - `failedAt` string, nullable: Timestamp when the item delivery failed - `returnedAt` string, nullable: Timestamp when the item was returned - `failureReason` string, nullable: Reason for delivery failure - `failureLocation` string, nullable: Where the failure occurred: 'pickup' or 'dropoff' - `statusHistory` ItemStatusHistoryEntrySerializer[], nullable: History of status changes for this item. - `status` string, required: Item status at this point in time - `createdAt` string, required: Timestamp of the status change - `occurredAt` string, nullable: Time the action happened on the driver's device, when known - `subItems` OrderItemSerializer[], nullable: Nested sub-items with their own status tracking. - `isDispatched` boolean: Whether the route is dispatched. - `jobId` string, nullable: Dispatched Job ID of this route - `routeMetadata` object, nullable: Additional metadata for the route. - `validationErrors` object, nullable: Validation errors for the route. - `encodedPolyline` string, nullable: Encoded polyline representing the route geometry. - `status` string, nullable: Current status of the route. - `statusHistory` object[], nullable: History of status changes for the route. ## Other responses - `422`: Unprocessable Content --- [API](https://skmtc.dev/nash/apis/nash-api.md) - [All operations](https://skmtc.dev/nash/apis/nash-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nash/apis/nash-api/revisions/e3713837c5c9?raw)