Bulk Updates

The bulk update API allows for efficient modification of multiple bookings or vehicles in a single asynchronous request. This is particularly useful for synchronization tasks where large sets of entities need to be updated to match an external system state.

The entry point for these operations is POST /api/v2/microservices/bulk/task api.

Booking Updates

The booking_update task type allows modification of specific fields across multiple bookings.

Supported Fields

The following fields are available for update. Any field not included in the payload will remain unchanged.

Field	Type	Description
min_pickup_time	DateTime (ISO8601)	Earliest allowed time for pickup. Affects planning constraints.
max_pickup_time	DateTime (ISO8601)	Latest allowed time for pickup.
min_dropoff_time	DateTime (ISO8601)	Earliest allowed time for drop-off.
max_dropoff_time	DateTime (ISO8601)	Latest allowed time for drop-off.
pickup_operations_location_external_id	String	Updates the pickup location to the coordinates of the specified operations location.
dropoff_operations_location_external_id	String	Updates the drop-off location to the coordinates of the specified operations location.
demand	Map<String, Int>	Partial update of the demand. Keys like volume, weight, or passengers can be updated individually without affecting others.
vehicle_labels	Map<String, Any>	Replaces the set of required vehicle labels/characteristics. Used for vehicle compatibility matching.
product_kind	String	Updates the classification of the product/service.
order_position	Enum	Constraints the order's position in a trip. Values: first_in_trip, last_in_trip.
data	Object	Updates the unstructured data blob. Supports fields like remarks, group, udf1, udf2, cluster_code, store_open_hours, etc.
customer_id	String	Updates the customer identifier associated with the booking.

Automatic Node and Route Updates

When you update fields that affect the core constraints of a booking, the system automatically propagates these changes to the underlying nodes and potentially triggers a reschedule of assigned vehicles.

• Node Updates: Changing time windows, demand, vehicle labels, or operations locations will automatically update the properties of the associated pickup and drop-off nodes.
• Route Updates: Changing operations locations (which define where the stop is) will trigger a route recalculation if the booking is already assigned to a vehicle.

tip

Be aware that updating fields dependent on the state of the booking might be restricted. For example, you cannot update time windows or demands for bookings that are already COMPLETED or CANCELLED. The system checks if the booking is in an appropriate state (e.g., NEW, PREPARED, ASSIGNED) before applying changes that affect nodes.

Vehicle Updates

The vehicle_update task type allows modification of vehicle properties.

Supported Fields

The following fields define the properties and constraints of a vehicle.

Field	Type	Description
service_number	String	The operational identifier for the vehicle (often displayed to users).
registration_number	String	The license plate or official registration number.
color	String	Visual identifier for the vehicle (e.g. Hex code or name).
driver_id	Integer	ID of the driver assigned to this vehicle.
vehicle_type_id	Integer	ID of the vehicle type (defines capacity, profile, etc.).
vehicle_cost	Float	Cost factor associated with using this vehicle in optimization.
geofence_ids	List<Integer>	List of geofence IDs the vehicle is restricted to or associated with.
start_time	DateTime (ISO8601)	The time the vehicle becomes available for service.
end_time	DateTime (ISO8601)	The time the vehicle service must end.
start_point	Object	Defines where the vehicle starts its shift. See Location Definitions below.
end_point	Object	Defines where the vehicle ends its shift. See Location Definitions below.

Location Definitions

For start_point and end_point, you can define the location using either:

1. Coordinates: Providing lat and lon.
2. Operations Location: Providing operations_location_external_id.

warning

You cannot provide both coordinates and an operations location ID for the same point. Mutually exclusive validation is applied.

Route Rebuilding

Changing the start_point or end_point of a vehicle is a significant change that affects the entire route structure.

tip

If you update the start or end locations of a vehicle, the system will automatically trigger a route rebuild. This attempts to reschedule all currently assigned nodes for that vehicle to accommodate the new start/end constraints.