---
title: "Reassign Route"
method: POST
path: "/orders/routes/{route_handle}/reassign"
tags: ["Orders"]
---

# Reassign Route

`POST /orders/routes/{route_handle}/reassign`

## Request

- Base URL: `https://v3.api.hypertrack.com`
- URL: `https://v3.api.hypertrack.com/orders/routes/{route_handle}/reassign`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
- TypeScript: <https://skmtc.dev/hypertrack/apis/hypertrack-api/docs/orders/routes/:route_handle/reassign/post.ts> (a function with typed inputs; its response is checked against the schema)

Reassign the route to a different worker. Please provide either a worker_handle or the device_id of the new worker to whom the route needs to be assigned.

## Path parameters

- `route_handle` string, required

## Query parameters

- `version` integer, nullable

## Request body

- ReassignRouteRequest
  - `driver_handle` string, nullable: Unique customer provided identifier for the new driver to whom the route needs to be assigned to
  - `worker_handle` string, nullable: Unique customer provided identifier for the new worker to whom the route needs to be assigned to
  - `device_id` string, nullable: Unique identifier for the device of the worker to whom the route needs to be assigned to

## Response `200`

Successful response

- ReassignRouteResponse
  - `route_handle` string, required: Unique identifier for the route
  - `status` 'planned' | 'assigned' | 'tracking' | 'completed' | 'summarizing', required: Current state of route
  - `version` integer, required: Value indicating the latest updated state of the route
  - `created_at` string, required: Timestamp at which the route was created
  - `embed_url` string, required: Embeddable link that renders the route profile view
  - `orders` RouteOrder[], required: List of orders to be fulfilled in the route
    - `order_handle` string, required: Unique customer provided identifier for an order
    - `status` 'planned' | 'assigned' | 'dispatched' | 'ongoing' | 'disabled' | 'cancelled' | 'completed' | 'summarizing' | 'unplanned', required: Current state of the order - `unplanned`, `planned`, `assigned`, `ongoing`, `completed`, `cancelled`
    - `destination` OrderDestinationSpecialType, required
      - `geofence_id` string, nullable: Geofence ID to extract geometry from
      - `place_handle` string, nullable: Place Handle to extract geometry from
      - `address` string, nullable: Address for the order destination
      - `geometry` union, required: GeoJSON representation of point geometry for the order destination
        - PointGeometry
          - `coordinates` number[], required: Location coordinates represented as [longitude, latitude]
          - `type` 'Point': Geometry type
        - PolygonGeometry
          - `type` 'Polygon', required: Geometry type
          - `coordinates` array[], required: Location coordinates represented as [[[longitude, latitude], [lon, lat]...]]
            - array[]
              - …
      - `place_id` string, nullable: Place ID
      - `radius` integer, nullable: Radius of the circular geofence representing the order destination
    - `fulfillment_attempt` integer, nullable: Number identifying the attempt count for the order
    - `risk_status` boolean, nullable: Flag indicating whether the order is at risk
    - `ops_group_handle` string, nullable: Unique identifier for the ops group to which the orders in the route are associated
    - `plan_mode` unknown
    - `plan_id` string, nullable: Order plans identifier
    - `planning_failure_reason` string, nullable: Reason explaining why automated planning left the order unplanned. Present only when a planning attempt could not assign the order.
    - `device_id` string, nullable: Unique identifier for a device
    - `driver_handle` string, nullable: Unique customer provided identifier for the driver
    - `worker_handle` string, nullable: Unique customer provided identifier for the worker
    - `place_handle` string, nullable: Unique customer provided identifier of the place
    - `created_at` string, nullable: Timestamp at which the order was created
    - `started_at` string, nullable: Timestamp at which the order tracking started
    - `assigned_at` string, nullable: Timestamp at which the order was assigned to a driver
    - `planned_at` string, nullable: Timestamp at which the order was planned into a route
    - `scheduled_at` string, nullable: Timestamp by which the order should be fulfilled to meet the customer promise
    - `scheduled_after` string, nullable: Timestamp after which the order should be fulfilled to meet the customer promise
    - `completed_at` string, nullable: Timestamp at which the order was completed
    - `cancelled_at` string, nullable: Timestamp at which the order was cancelled
    - `disabled_at` string, nullable: Timestamp at which the order was disabled so that it can be fulfillment later
    - `enabled_at` string, nullable: Timestamp at which the disabled order was enabled for fulfillment
    - `arrived_at` string, nullable: Timestamp at which the driver arrived at the order fulfillment location
    - `exited_at` string, nullable: Timestamp at which the driver exited from the order fulfillment location
    - `metadata` object, nullable: Additional customer provided information about the order
    - `risks` object, nullable: Object containing different risk statuses for the order
    - `expected_service_time` integer, nullable: Time in seconds that the driver is expected to spend at the location when fulfilling the order
    - `product_type` string[], nullable: List of customer provided product/service types used when matching orders to a driver
    - `type` unknown
    - `type_index` integer, nullable: Field to specify the index of type
    - `capacity_used` integer, nullable: Volumetric unit occupied by the order
    - `region` union: City, state, and country where the orders needs to be fulfilled
      - Region
        - `country` string, required: Country
        - `city` string, nullable: City
        - `state` string, nullable: State
      - unknown
    - `distance` integer, nullable: Total distance in meters travelled by the driver to reach the order location
    - `duration` integer, nullable: Total time in seconds spent on the order.
    - `estimate` union: Object containing the estimate information for the order that has not been completed
      - OrderListEstimate
        - `start_at` string, nullable: Deprecated: use `start_by`. Always returns the same value as `start_by`.
        - `start_by` string, nullable: Latest time the worker can leave their current (or planned start) location and still reach this order by its `scheduled_at`, following the route sequence and the remaining service time at earlier stops. Computed by planning and once at the first tracking ETA, which uses traffic for the planned arrival time. `null` when the order has no `scheduled_at`.
        - `arrive_at` string, nullable: Estimated timestamp by which a driver should arrive at order destination
        - `distance` integer, nullable: Estimated total distance that the driver should travel
        - `duration` integer, nullable: Estimated total time that the driver should spend to fulfill all orders in the route
        - `initial_arrive_at` string, nullable: Initial Estimated timestamp by which a driver should arrive at the destination
        - `current_worker_location` union: Current Worker location details
          - DriverLocation
            - `geometry` LocationGeometryResponse, required
              - …
            - `bearing` number, required: Bearing of the driver
            - `accuracy` number, required: Accuracy of location the driver
            - `speed` number, required: Speed of the driver
            - `recorded_at` string, required: Time when the location of the driver was recorded
          - unknown
      - unknown
    - `share_url` string, nullable: Shareable URL for the consumer to track the live movement of the drive after the order is dispatched
    - `route_handle` string, nullable: Unique identifier for the route
    - `track_mode` unknown
    - `actual_service_time` integer, nullable: Time in seconds that the driver is actually spent at the location when fulfilling the order
    - `tracked_service_time` integer, nullable: Time in seconds that the driver was tracked at the location when fulfilling the order
    - `tracking_rate` number, nullable: Indicates the ratio of time tracked to expected tracking time of order. Values lie between 0.0 and 1.0
    - `time_to_first_event` number, nullable: Time in seconds to receive first event from device after order start
    - `time_to_first_location` number, nullable: Time in seconds to receive first location from device after order start
    - `created_by` union: Source of the order creation. This can be a user, system, or any other entity responsible for creating the order.
      - Source
        - `source` string, nullable: Source of the request
        - `timestamp` string, nullable: Time when request was made
        - `ip-address` string, nullable: IP address of source
        - `device_id` string, nullable: Id of the device that made the request
        - `driver_handle` string, nullable: Id of the driver who made the request
        - `user_id` string, nullable: Id of the user who made the request
        - `email` string, nullable: Email of the user who made the request
      - unknown
    - `outage_summary` OrderOutageSummary[], nullable: List of outages experienced during the specified time range.
      - `duration` integer, required: Sum total duration of all outages experienced with this `code` in the specified time range.
      - `distance` integer: Sum total (estimated) distance covered during all outages experienced with this `code` in the specified time range.
      - `code` string, required: Code indicating the type of outage
      - `label` string, required: Text indicating the type of outage
      - `description` string, required: Text describing the outage.
      - `category` 'behavioural' | 'adversarial' | 'reachability' | 'os' | 'sporadic' | 'null', nullable: String indicating the category of outage
    - `embed_url` string, nullable: Embeddable URL for the ops team to view order timeline
    - `device_switch_mode` unknown
    - `tasks` OrderTask[], nullable: List of tasks associated with the order.
      - `label` string, required: Type of task to be created for the order.
      - `task_definition_id` string, nullable: Id of the tasks definition from which this task is picked
      - `description` string, nullable: Description of the task type.
      - `metadata` object, nullable: Additional metadata for the task.
      - `priority` 'none' | 'low' | 'medium' | 'high' | 'null', nullable: Priority of the task. Valid values are none, low, medium, high.
      - `task_id` string, required: Unique identifier for the created task.
      - `status` string, nullable: Status of the task. Valid values are pending, ongoing, completed, cancelled.
    - `priority` unknown
    - `worker_profile` object, nullable: Metadata associated with a driver
    - `rescheduled_marked_at` string, nullable: Timestamp at which the order was rescheduled
    - `cancellation_source` object, nullable: Detail about how order got cancelled
    - `cancellation_reason` string, nullable: Customer-reported reason why the shift did not occur as planned: `no_show`, `worker_cancelled`, `client_cancelled`, `other`. Consumers must accept new values.
    - `timesheets` union[], nullable: Timesheet entries for the order. Includes HyperTrack-computed (HypertrackLocationTimesheet) and customer-provided entries.
      - union
        - HypertrackLocationTimesheet
          - `source` string, required: Always hypertrack-location. Identifies this as a HyperTrack-computed entry.
          - `type` string, required: Always location. Distinguishes this computation type from future types.
          - `start_time` string, nullable: ISO 8601 timestamp when the worker arrived on site (first geofence entry). Null if the worker never entered the destination geofence.
          - `end_time` string, nullable: ISO 8601 timestamp when the worker left the site (last geofence exit). Null if the worker was still inside at order closure.
          - `total_duration_on_premises` integer, required: Total seconds the worker spent at the destination (sum of geofence visit durations).
          - `total_break_duration` integer, required: Residual seconds not at the destination. Equals (end_time - start_time) - total_duration_on_premises.
          - `breaks` BreakEntry[], nullable: Geofence exit→re-entry windows representing time away from the destination. Each entry has start_time, end_time, and duration (seconds). Null when there are no exit→re-entry gaps.
            - `type` string, required: Break type (e.g. "meal", "rest").
            - `start_time` string, required: ISO 8601 timestamp when the break started.
            - `end_time` string, required: ISO 8601 timestamp when the break ended.
            - `duration` integer, required: Break duration in seconds.
          - `finalized` boolean, required: Always true. Signals this entry was computed at order completion and will not change.
        - object
  - `created_by` union: Source of the route creation. This can be a user, system, or any other entity responsible for creating the route.
    - Source
      - `source` string, nullable: Source of the request
      - `timestamp` string, nullable: Time when request was made
      - `ip-address` string, nullable: IP address of source
      - `device_id` string, nullable: Id of the device that made the request
      - `driver_handle` string, nullable: Id of the driver who made the request
      - `user_id` string, nullable: Id of the user who made the request
      - `email` string, nullable: Email of the user who made the request
    - unknown
  - `ops_group_handle` string: URL safe unique identifier for the ops group to which the orders in the route are associated
  - `track_mode` 'full_shift' | 'on_shift' | 'pre_shift' | 'null', nullable: Value representing whether the route is tracked in on_shift, pre_shift or full_shift mode
  - `plan_mode` 'on_demand' | 'scheduled' | 'manual' | 'null', nullable: Value indicating how the orders in the route were planned
  - `started_at` string, nullable: Timestamp at which the route tracking started
  - `assigned_at` string, required: Timestamp at which the route was assigned to a driver
  - `planned_at` string, nullable: Timestamp at which the orders were planned into this route
  - `completed_at` string, nullable: Timestamp at which the route was completed
  - `device_id` string, nullable: Unique identifier for a device
  - `driver_handle` string, nullable: Unique customer provided identifier for the driver
  - `worker_handle` string, nullable: Unique customer provided identifier for the worker
  - `metadata` object, nullable: Additional customer provided information about the route
  - `region` union: City, state, and country where the orders in the route are being fulfilled
    - Region
      - `country` string, required: Country
      - `city` string, nullable: City
      - `state` string, nullable: State
    - unknown
  - `distance` integer, nullable: Actual distance travelled by the driver to fulfill all orders in the route
  - `duration` integer, nullable: Actual time spent by the driver to fulfill all orders in the route
  - `estimate` union: Object containing the estimate information for routes that have not been completed
    - RouteDetailEstimate
      - `start_by` string, nullable: Latest time the worker can leave the planned start location and still reach every scheduled order in the route on time, following the route sequence and service times. Orders without `scheduled_at` use a placeholder deadline. Computed at planning.
      - `distance` integer, required: Estimated total distance that the driver should travel in the route
      - `duration` integer, required: Estimated total time that the driver should spend to fulfill all orders in the route
      - `polyline` EstimatePolyline, required
        - `type` string, required: Type of GeoJSON feature. It will always be `LineString` for polyline
        - `coordinates` array[], required: GeoJSON representation of LineString coordinates, inner list element is represented as [longitude, latitude]
          - unknown[]
            - unknown
      - `start_location` union: The starting point location from where the driver begins their journey for the route
        - LocationGeometryResponse
          - `type` string, required: Geometry type
          - `coordinates` unknown[], required: Location coordinates represented as list of [longitude, latitude].
            - unknown
        - unknown
      - `end_location` union: The final destination location where the route ends after completing all orders
        - LocationGeometryResponse
          - `type` string, required: Geometry type
          - `coordinates` unknown[], required: Location coordinates represented as list of [longitude, latitude].
            - unknown
        - unknown
    - unknown
  - `plan_id` string, nullable: Unique identifier for the plan to which the route belongs to
  - `device_switch_mode` unknown
  - `candidate_devices` string[], nullable: List of devices among which the route is expected to be tracked
  - `completion_source` string, nullable: Source of the route completion
  - `scheduled_start_at` string, nullable: Scheduled start time of the route
  - `polyline` union: LineString of actual coordinates traversed by the driver to fulfill the orders in the route
    - Polyline
      - `type` string, required: Type of GeoJSON feature. It will always be `LineString` for polyline
      - `coordinates` array[], required: GeoJSON representation of LineString coordinates, inner list element is represented as [longitude, latitude, altitude, recorded_at]
        - unknown[]
          - unknown
    - unknown
  - `start_location` union: Location where the driver started tracking to fulfill the orders in the route
    - LocationGeometryResponse
      - `type` string, required: Geometry type
      - `coordinates` unknown[], required: Location coordinates represented as list of [longitude, latitude].
        - unknown
    - unknown
  - `end_location` union: Location where the driver stopped tracking after completing all orders in the route
    - LocationGeometryResponse
      - `type` string, required: Geometry type
      - `coordinates` unknown[], required: Location coordinates represented as list of [longitude, latitude].
        - unknown
    - unknown
  - `tracking_rate` number, nullable: Indicates the ratio of time tracked to expected tracking time of route. Values lie between 0.0 and 1.0
  - `time_to_first_event` number, nullable: Time in seconds to receive first event from device after tracking start
  - `time_to_first_location` number, nullable: Time in seconds to receive first location from device after tracking start
  - `completion_type` 'end_at_last_order' | 'return_to_start_location' | 'manual' | 'null', nullable: Configuration to identify where routes are expected to end

## Other responses

- `400`: Validation error
- `401`: Authentication error
- `404`: Not found

---

[API](https://skmtc.dev/hypertrack/apis/hypertrack-api.md) - [All operations](https://skmtc.dev/hypertrack/apis/hypertrack-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hypertrack/apis/hypertrack-api/revisions/389326c4c9c8?raw)