Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ShohjahonSohibov/repo-for-agent/llms.txt

Use this file to discover all available pages before exploring further.

Load management is the core of UpdaterAgent TMS. This page covers how loads are structured, how they move through their lifecycle from creation to delivery, and how dispatchers interact with stops, routing, and file attachments throughout the process.

​
Load lifecycle

Loads follow a defined status progression. Every load starts as Upcoming and advances as dispatchers and drivers take action. Cancellation is possible at any point before delivery. 
Upcoming → Dispatched → InTransit → Delivered
                                   ↘ Cancelled
Status transitions are one-directional. A load cannot be moved backward in the lifecycle (e.g., from InTransit back to Dispatched). Use the PUT /api/loads/{id}/start and PUT /api/loads/{id}/complete endpoints to advance status.

​
Key load properties

Each load record carries the following core fields:
PropertyTypeDescription
TripNumberstringUnique trip identifier, used for deduplication on import
StatusenumCurrent lifecycle status (Upcoming, Dispatched, InTransit, Delivered, Cancelled)
TypeenumLoad type (e.g., dry van, flatbed, reefer)
CommoditystringDescription of the freight being hauled
WeightdecimalFreight weight
CompanyIdlongOwning company (tenant-scoped)
CustomerIdlongAssociated customer/broker record

​
Multi-stop routing

Loads contain an ordered list of stops representing pickup and delivery locations. Stops are ordered by AppointmentDate. Each stop carries:
  • IsPickup — whether the stop is a pickup (true) or delivery (false)
  • AppointmentDate — scheduled time at the stop, used for ordering
  • AddressId — linked address with geocoded coordinates
  • AssignedTruckId — truck responsible for this stop
  • AssignedDriverIds — list of driver IDs (stored as Driver.Id, not ImportId)
  • IsCurrentHeading — whether the truck is currently en route to this stop

​
Current heading

The system tracks which stop a truck is actively heading toward via the IsCurrentHeading flag on the Stop entity. Set heading explicitly: 
PATCH /api/update-board/{truckId}/heading
Content-Type: application/json

{
  "loadId": 123,
  "stopId": 456
}
The system validates that:
  • The load is active (Upcoming, Dispatched, or InTransit)
  • The stop belongs to the load
  • The stop is assigned to the specified truck
  • The stop has not already been completed
Auto-advance on check-in: When a driver checks in to a stop, the system automatically advances the heading:
  1. Clears IsCurrentHeading = false on the current stop
  2. Finds the next uncompleted stop on the same load and truck, ordered by AppointmentDate
  3. Sets IsCurrentHeading = true on that stop
  4. If no next stop exists (last stop checked in), heading is left unset
If no stop has IsCurrentHeading = true, the system falls back to the first uncompleted stop ordered by AppointmentDate.

​
Stop operations

Stops move through their own state as the driver progresses:
OperationEndpointDescription
Check inPUT /api/stops/{id}/checkinDriver has arrived at the stop
Check outPUT /api/stops/{id}/checkoutDriver has departed the stop
CompletePUT /api/stops/{id}/completeStop is fully finalized

​
ETA calculation

UpdaterAgent calculates ETA to the current heading stop using a hybrid routing strategy:
  1. OSRM (primary) — free, self-hosted OpenStreetMap routing
  2. Google Maps (fallback) — used when OSRM distance exceeds 2× the straight-line distance, or when OSRM is unavailable
ETAs are available via GET /api/loads/{id}/eta and are also included in update board responses.

​
File attachments

Loads support document attachments for compliance and proof of delivery:
  • BOL — Bill of Lading
  • POD — Proof of Delivery
  • Rate Confirmation — Agreed rate documentation
POST /api/loads/{id}/files
Content-Type: multipart/form-data

file: <binary>
fileType: BOL
Supported formats: PDF, JPEG, PNG. Maximum file size: 10 MB.

​
Typical load workflow

1

Create the load

Create a new load via POST /api/loads or let the system import it automatically from QuickManage TMS via webhook or the scheduled tms-import:load job (runs every 3 hours). The load starts with status Upcoming.
2

Assign a driver

Assign a driver to the load using POST /api/loads/{id}/assign-driver. The driver’s Driver.Id (local database PK) is stored in each stop’s AssignedDriverIds field.
3

Dispatch the load

Advance status to Dispatched to signal the load is ready for pickup. The driver and dispatcher receive notifications via Telegram.
4

Start transit

Call PUT /api/loads/{id}/start when the driver begins moving. Status changes to InTransit and ETA tracking becomes active.
5

Progress through stops

As the driver arrives at each stop, use the check-in, check-out, and complete endpoints. The system auto-advances the current heading after each check-in.
6

Upload documents

Upload BOL and POD documents using POST /api/loads/{id}/files as the driver completes pickups and deliveries.
7

Complete the load

Call PUT /api/loads/{id}/complete once all stops are finished. Status changes to Delivered.

​
Key endpoints

MethodPathDescription
GET/api/loadsList loads with filters and pagination
GET/api/loads/{id}Get load details including stops
POST/api/loadsCreate a new load
PUT/api/loads/{id}Update load details
POST/api/loads/{id}/assign-driverAssign driver to load
PUT/api/loads/{id}/startSet status to InTransit
PUT/api/loads/{id}/completeSet status to Delivered
GET/api/loads/{id}/etaGet current ETA to next stop
POST/api/loads/{id}/filesUpload BOL, POD, or Rate Confirmation
GET/api/loads/{id}/filesList load file attachments
DELETE/api/loads/{id}/files/{fileId}Delete a load file
PUT/api/stops/{id}/checkinMark stop as checked in
PUT/api/stops/{id}/checkoutMark stop as checked out
PUT/api/stops/{id}/completeMark stop as completed
PATCH/api/update-board/{truckId}/headingSet which stop the truck is heading to

Build docs developers (and LLMs) love

Get started for freeTalk to us