Loads API: create, update, and track freight

The Loads API is the core of UpdaterAgent TMS. It exposes endpoints to create and update freight loads, drive them through the Upcoming → Dispatched → InTransit → Delivered lifecycle, assign drivers, manage document attachments (BOL, POD), and retrieve real-time ETA to the next stop. All endpoints require a valid JWT and the appropriate permission. Base URL: /api/loads Required permission (minimum): Loads.View

Load status lifecycle

Every load starts as Upcoming and advances forward — status transitions are one-directional.

Upcoming → Dispatched → InTransit → Delivered
                                   ↘ Cancelled

Use PUT /api/loads/{id}/start to move from Dispatched → InTransit, and PUT /api/loads/{id}/complete to move from InTransit → Delivered.

Endpoints

GET /api/loads

List loads with optional filters and pagination. Requires Loads.View. Query parameters

page

number

Page number, 1-indexed. Defaults to 1.

pageSize

number

Items per page. Defaults to 20, maximum 100.

sortBy

string

Field name to sort results by (e.g., createdAt, status).

sortDirection

string

Sort order: asc or desc.

status

string

Filter by load status: Upcoming, Dispatched, InTransit, Delivered, or Cancelled.

companyId

number

Filter loads belonging to a specific company.

fromDate

string

ISO 8601 date — return loads created on or after this date.

toDate

string

ISO 8601 date — return loads created on or before this date.

string

Text search across trip number, commodity, and related fields.

Response

items

array

required

Array of load summary objects for the current page.

totalCount

number

required

Total number of loads matching the filters.

page

number

required

Current page number.

pageSize

number

required

Number of items per page.

totalPages

number

required

Total number of pages.

curl "https://your-domain.com/api/loads?status=InTransit&page=1&pageSize=20" \
  -H "Authorization: Bearer <accessToken>"

GET /api/loads/

Get detailed load information including all associated stops. Requires Loads.View. Path parameters

number

required

The load ID.

cURL

curl https://your-domain.com/api/loads/101 \
  -H "Authorization: Bearer <accessToken>"

POST /api/loads

Create a new load. Requires Loads.Create. Request body

tripNumber

string

required

Unique trip identifier. Used for deduplication on QuickManage import.

companyId

number

required

The owning company ID (tenant-scoped).

customerId

number

Associated broker or customer record ID.

commodity

string

Description of the freight being transported.

weight

number

Freight weight.

type

string

Load type (e.g., DryVan, Flatbed, Reefer).

curl -X POST https://your-domain.com/api/loads \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "tripNumber": "TRP-5099",
    "companyId": 3,
    "customerId": 12,
    "commodity": "Auto Parts",
    "weight": 18000,
    "type": "DryVan"
  }'

PUT /api/loads/

Update an existing load’s details. Requires Loads.Update. Path parameters

number

required

The load ID to update.

Request body The body accepts the same fields as POST /api/loads. Include only the fields you want to change.

cURL

curl -X PUT https://your-domain.com/api/loads/210 \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"commodity": "Auto Parts — Revised", "weight": 19500}'

DELETE /api/loads/

Delete a load record. Requires Loads.Delete.

Deletion is soft-delete only — the record is marked as deleted and excluded from all future queries, but it is not purged from the database.

Path parameters

number

required

The load ID to delete.

cURL

curl -X DELETE https://your-domain.com/api/loads/210 \
  -H "Authorization: Bearer <accessToken>"

GET /api/loads/statistics

Return a count of loads grouped by status. Useful for dashboard tiles and pipeline summaries. Requires Loads.View.

cURL

curl https://your-domain.com/api/loads/statistics \
  -H "Authorization: Bearer <accessToken>"

Response

{
  "upcoming": 14,
  "dispatched": 7,
  "inTransit": 23,
  "delivered": 512,
  "cancelled": 6
}

POST /api/loads//assign-driver

Assign a driver to a load. Requires Loads.Update. Path parameters

number

required

The load ID.

Request body

driverId

number

required

The driver’s local database ID (Driver.Id). Do not use ImportId.

driverId must be the local Driver.Id (long), not the external ImportId used for QuickManage synchronization. See the Drivers API for details on this distinction.

cURL

curl -X POST https://your-domain.com/api/loads/101/assign-driver \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"driverId": 42}'

PUT /api/loads//start

Set load status to InTransit. Use this when the driver begins transit. Requires Loads.Update. Path parameters

number

required

The load ID.

cURL

curl -X PUT https://your-domain.com/api/loads/101/start \
  -H "Authorization: Bearer <accessToken>"

PUT /api/loads//complete

Set load status to Delivered. Use this when all stops are finished. Requires Loads.Update. Path parameters

number

required

The load ID.

cURL

curl -X PUT https://your-domain.com/api/loads/101/complete \
  -H "Authorization: Bearer <accessToken>"

POST /api/loads//files

Upload a document (BOL, POD, or similar) to a load. Requires Loads.Update. Path parameters

number

required

The load ID.

Request body — multipart/form-data

file

required

The file to upload. Supported types: PDF (application/pdf), JPEG (image/jpeg), PNG (image/png). Maximum size: 10 MB.

fileType

string

required

Document category: BOL (Bill of Lading), POD (Proof of Delivery), or RateCon (Rate Confirmation).

cURL

curl -X POST https://your-domain.com/api/loads/101/files \
  -H "Authorization: Bearer <accessToken>" \
  -F "file=@/path/to/bol.pdf;type=application/pdf" \
  -F "fileType=BOL"

GET /api/loads//files

List all file attachments for a load. Requires Loads.View. Path parameters

number

required

The load ID.

cURL

curl https://your-domain.com/api/loads/101/files \
  -H "Authorization: Bearer <accessToken>"

Response

[
  {
    "id": 7,
    "loadId": 101,
    "fileType": "BOL",
    "fileName": "bol.pdf",
    "uploadedAt": "2025-06-10T09:14:00Z"
  }
]

DELETE /api/loads//files/

Delete a specific file attachment from a load. Requires Loads.Delete. Path parameters

number

required

The load ID.

fileId

number

required

The file attachment ID to delete.

cURL

curl -X DELETE https://your-domain.com/api/loads/101/files/7 \
  -H "Authorization: Bearer <accessToken>"

GET /api/loads//eta

Get the current ETA to the next (or current heading) stop. Requires Loads.View. ETA is calculated using OSRM as the primary routing engine, with Google Maps as a fallback. Path parameters

number

required

The load ID.

cURL

curl https://your-domain.com/api/loads/101/eta \
  -H "Authorization: Bearer <accessToken>"

Response

{
  "loadId": 101,
  "nextStopId": 456,
  "eta": "2025-06-10T17:45:00Z",
  "remainingMinutes": 93,
  "destinationAddress": "1400 Industrial Blvd, Dallas, TX 75207"
}

PATCH /api/update-board//heading

Set the stop that a truck is currently heading toward. This endpoint lives under UpdateBoardController but directly affects load stop state. Requires Loads.Update. Path parameters

truckId

number

required

The truck ID.

Request body

loadId

number

required

The load ID the stop belongs to. The load must be active (Upcoming, Dispatched, or InTransit).

stopId

number

required

The stop ID to set as the current heading. The stop must belong to the load, be assigned to the given truck, and not yet be completed.

curl -X PATCH https://your-domain.com/api/update-board/9/heading \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"loadId": 101, "stopId": 456}'

If no stop has IsCurrentHeading = true, the system falls back to the first uncompleted stop ordered by AppointmentDate. The heading flag is also auto-advanced on check-in — see the Stops API for details.

Pagination

All list endpoints use consistent pagination query parameters and response structure.

GET /api/loads?page=2&pageSize=50&sortBy=createdAt&sortDirection=desc

{
  "items": [...],
  "totalCount": 150,
  "page": 2,
  "pageSize": 50,
  "totalPages": 3
}

Error responses

404 Not Found — load does not exist

{
  "error": {
    "code": "Load.NotFound",
    "message": "Load with ID 123 was not found"
  }
}

409 Conflict — duplicate trip number

{
  "error": {
    "code": "Load.DuplicateTripNumber",
    "message": "Load with TripNumber 12345 already exists"
  }
}

Permissions summary

Permission	Grants access to
`Loads.View`	GET endpoints, statistics, ETA, file listing
`Loads.Create`	`POST /api/loads`
`Loads.Update`	PUT, PATCH, assign-driver, start, complete, file upload
`Loads.Delete`	DELETE load, DELETE file

Authentication

Logistics

Operations

Configuration

Loads API: create, update, and track freight

Load status lifecycle

Endpoints

GET /api/loads

GET /api/loads/

POST /api/loads

PUT /api/loads/

DELETE /api/loads/

GET /api/loads/statistics

POST /api/loads//assign-driver

PUT /api/loads//start

PUT /api/loads//complete

POST /api/loads//files

GET /api/loads//files

DELETE /api/loads//files/

GET /api/loads//eta

PATCH /api/update-board//heading

Error responses

Permissions summary

Build docs developers (and LLMs) love

Authentication

Logistics

Operations

Configuration

Documentation Index

​Load status lifecycle

​Endpoints

​GET /api/loads

​GET /api/loads/

​POST /api/loads

​PUT /api/loads/

​DELETE /api/loads/

​GET /api/loads/statistics

​POST /api/loads//assign-driver

​PUT /api/loads//start

​PUT /api/loads//complete

​POST /api/loads//files

​GET /api/loads//files

​DELETE /api/loads//files/

​GET /api/loads//eta

​PATCH /api/update-board//heading

​Pagination

​Error responses

​Permissions summary

Build docs developers (and LLMs) love

Load status lifecycle

Endpoints

GET /api/loads

GET /api/loads/

POST /api/loads

PUT /api/loads/

DELETE /api/loads/

GET /api/loads/statistics

POST /api/loads//assign-driver

PUT /api/loads//start

PUT /api/loads//complete

POST /api/loads//files

GET /api/loads//files

DELETE /api/loads//files/

GET /api/loads//eta

PATCH /api/update-board//heading

Pagination

Error responses

Permissions summary