Dispatch Route

Dispatch routes are daily operational routes assigned to drivers. A route has a date, route type, status, optional driver/equipment/division assignment, and an ordered list of stops. Routes can be created manually or generated from dispatch route templates.

DispatchRoute

Property	Type	Required	Description
DispatchRouteId	int	Yes	Primary key
OrganizationId	int	Yes	Tenant scope
Name	string	Yes	Route name
RouteType	DispatchRouteType	Yes	Delivery, Pickup, or PickupDelivery
RouteDate	Date	Yes	Operational route date (yyyy-MM-dd)
DispatchRouteStatusId	int	Yes	Current route status
DispatchRouteTemplateId	int?	No	Source template when generated
DivisionId	int?	No	Optional division assignment
DriverContactId	int?	No	Assigned driver contact; must be a driver contact
EquipmentId	int?	No	Assigned equipment
IsDraft	bool	Yes	New/generated routes start as drafts
IsInactive	bool	Yes	Soft-delete flag
CollapsedIntoDispatchRouteId	int?	No	Route this route was merged into
Stops	DispatchRouteStop[]	No	Ordered route stops
TrackingEvents	TrackingEvent[]	No	Tracking events linked directly to the route
CustomValues	Dictionary	No	Extensible custom properties

DispatchRouteStop

Property	Type	Required	Description
DispatchRouteStopId	int	Yes	Primary key
DispatchRouteId	int	Yes	Parent route
StopContactId	int?	No	Store/location contact (nullable; use with or without contactAddressId)
ContactAddressId	int?	No	Specific stop address
StopType	DispatchRouteType	Yes	Defaults to the parent route type when omitted
PlannedSequence	int	Yes	1-based planned stop order
ActualSequence	int?	No	Final execution order
EstimatedServiceMinutes	int?	No	Planned dwell/service time
DispatchRouteStopStatusId	int?	No	Current stop-level status
DispatchRouteStopStatus	DispatchRouteStopStatus?	No	Optional expanded stop status
ActualArrivalTime	DateTime?	No	Actual arrival timestamp
ActualCompletionTime	DateTime?	No	Actual completion timestamp
OrderIds	int[]	No	Attached order IDs for this stop
Orders	DispatchRouteStopOrder[]	No	Attached order links; expand order when full order data is needed
TrackingEvents	TrackingEvent[]	No	Tracking events linked directly to this stop
CustomValues	Dictionary	No	Extensible custom properties (use for ad-hoc stop address when not using a contact)

DispatchRouteStopOrder

Property	Type	Required	Description
DispatchRouteStopOrderId	int	Yes	Primary key
DispatchRouteStopId	int	Yes	Parent stop
OrderId	int	Yes	Attached order
Order	Order?	No	Optional expanded order
DispatchRouteStop	DispatchRouteStop?	No	Optional expanded stop when reached from an order
CustomValues	Dictionary	No	Extensible custom properties for the stop/order link

Behavior

• Create accepts nested stops; planned sequences are assigned contiguously in input order. Stops may attach orders through orderIds.
• Route updates can replace the nested stops array. Existing stops with dispatchRouteStopId are sparse-updated and resequenced by array order; new stops are added; omitted existing stops are soft-deleted. Stop orderIds reconcile the attached orders to exactly the provided IDs when present. Stop dispatchRouteStopStatusId values are validated against the organization and stop type.
• updateDispatchRouteStop is a sparse dynamic update: only keys present in values are changed, an explicit null clears a nullable field, and omitted fields remain unchanged. This supports stamping or clearing actualArrivalTime and actualCompletionTime without resending the rest of the stop.
• Draft routes become operational through activateDispatchRoute.
• Stops cannot be removed, and routes cannot be deleted, when stops have attached orders.
• Removing or reordering a stop resequences remaining active stops.
• Generated routes copy template name, route type, division, and stops; driver/equipment assignment happens later.
• Stop location/order anchor: A stop's location is either a contact address (contactAddressId, optionally with stopContactId) or an ad-hoc address placed in customValues; alternatively, an order-attached stop can be created with orderIds. A stop must have at least one of stopContactId / contactAddressId / non-empty customValues / non-empty orderIds.
• Tracking events can be linked to a route or a specific stop. Use route-level events for whole-route milestones and stop-level events for arrival, completion, exception, or proof-of-service milestones tied to one stop.
• TrackingEvent/Create@1 can attach an event with dispatchRouteId or dispatchRouteStopId. TrackingEvent/Import@1 accepts exactly one of orderId, dispatchRouteId, or dispatchRouteStopId and performs duplicate matching against that target's existing events.