Alternate Assignments

What are alternate assignments?

Order-to-vehicle assignment is often a multi-candidate problem—several drivers may be eligible to fulfill a task based on availability, proximity, or service-level constraints. In such scenarios, returning only the single top recommendation can be limiting, especially when fallback logic or manual overrides are required downstream.

The alternate assignments feature in the Driver Assignment API addresses this by returning up to three viable vehicle alternatives per order, in addition to the primary match—giving platforms the power to support fallback logic, driver bidding flows, or manual assignment override based workflows. This capability is especially useful in fast-moving environments like last-mile delivery, field service dispatching, ride-hailing, or NEMT scheduling, where real-time decisions often need backup options to maintain service levels.

How to enable alternate assignments for vehicles?

To enable alternate assignments when submitting a request for driver matching, specify the number of additional assignments required using the alternate_asignments parameter under options. Once specified, the API responds with an extra attribute with details of potential matches for each feasible order given in the input.

Example: API Request with Alternate Assignments configuration

In the example below, we simulate a driver assignment problem where three pickup orders need to be matched with four available vehicles. Each order specifies attribute-based preferences—some require “premium” trip types, while others require “economy”. The vehicle pool includes a mix of drivers who can handle either or both categories. To increase flexibility, we configure the API with “alternate_assignments”: 2, which ensures that, in addition to the top recommended vehicle, up to two alternate options are returned for each order. This setup allows downstream systems or dispatchers to review fallback choices in case the primary driver becomes unavailable or a manual override is required.

Sample Request

1
curl --location 'https://api.nextbillion.io/optimization/driver-assignment/v1?key=<you_api_key>'   
2
--header 'Content-Type: application/json'   
3
--data '{  
4
 "filter": {...},  
5
 "orders": {...},  
6
 "vehicles": {...}  
7
}

Sample Response

1
{
2
  "status": 200,
3
  "result": {
4
      "trips": [...],
5
      "alternate_assignments": [...],
6
      "unassigned_orders": [...],
7
      "available_vehicles": [...]
8
  }
9
}

Looking at the response, following important points stand out:

  1. Primary Assignments: Each of the three pickup orders (Pickup 1, Pickup 2, Pickup 3) has been matched with a vehicle (v1, v4, and v2 respectively). The response shows each trip with details like the assigned vehicle, ETA to pickup, and distance from the current vehicle location.

  2. Alternate Assignments: For each order, up to two alternate vehicle options are listed under alternate_assignments. These provide backup driver choices along with their expected pickup ETAs, which is valuable when the primary driver is unavailable or rejects the primary trips for any reasons.

  3. Further we note that there were no unassigned orders as the unassigned_orders field is empty, and that vehicle “v3” is still available for future dispatches, helping with resource visibility.

Alternate Assignment Workflow

Since the alternate assignments were requested, the system, upon receiving the request, performed the following operations:

  1. Initial Matching: The optimizer first assigns each order to the best-suited vehicle (based on travel time, location, and order preferences). For example, “Pickup 1” is initially assigned to “v1”.

  2. Evaluating Backup Options: The system then evaluates other vehicles in the pool and lists feasible backup choices for all orders in the requests. For “Pickup 1”, if “v1” becomes unavailable, dispatchers can switch to “v4” (ETA 543s) or “v2” (ETA 1044s).

  3. List Unassigned Orders and Vehicles: As a final step the system then identifies the orders which remained unassigned and vehicles which were not assigned to any orders. For “v3”, is not assigned to any orders in the primary match, but remains available for future dispatches or for alternate assignments, for “Pickup 2” in this case, if required.

Explore the advanced capabilities of the Driver Assignment API to achieve rapid and efficient on-demand order fulfillment.