Field dictionary

Every response field, its semantics, and the honest list of what the API doesn't provide.

Every load row carries exactly the fields below — nothing optional, nothing undocumented. Fields that can be null are null when we don't have the value (not empty strings). Decimal quantities (miles, totalCost) are strings to preserve exact precision; parse them with a decimal type, not a float, if you do arithmetic.

Identity & references

API field	Type	Nullable	Semantics
`loadNumber`	string	no	FR8 Factory load number — the stable identity both parties quote. Upsert on this.
`poNumber`	string	yes	Your PO number, as entered on the load.
`billingRefNumber`	string	yes	Your billing reference, as entered on the load.

Origin & destination

API field	Type	Nullable	Semantics
`originCity`	string	yes	Pickup city.
`originState`	string	yes	Pickup state (2-letter).
`originZip`	string	yes	Pickup ZIP.
`originWarehouse`	string	yes	Pickup warehouse name — populated only when the pickup stop is a warehouse we have on record; expect `null` for one-off addresses.
`destinationCity`	string	yes	Delivery city.
`destinationState`	string	yes	Delivery state (2-letter).
`destinationZip`	string	yes	Delivery ZIP.
`destinationWarehouse`	string	yes	Delivery warehouse name — same caveat as `originWarehouse`.

Dates & schedule

All dates are ISO 8601 (UTC). Appointment times are separate string fields in the facility's local time, because that's how appointments are actually booked.

API field	Type	Nullable	Semantics
`scheduledPickupDate`	datetime	yes	Scheduled pickup appointment date.
`scheduledPickupTime`	string	yes	Scheduled pickup appointment time (local, e.g. `"08:00"`).
`scheduledDeliveryDate`	datetime	yes	Scheduled delivery appointment date.
`scheduledDeliveryTime`	string	yes	Scheduled delivery appointment time (local).
`tenderedDate`	datetime	yes	When the load was tendered to us.
`actualPickupDate`	datetime	yes	Driver checked in at origin. `null` until pickup happens.
`actualDeliveryDate`	datetime	yes	Driver checked in at destination. `null` until delivery happens.
`requestedDeliveryDate`	datetime	yes	Your requested delivery date.
`updatedAt`	datetime	no	Last value-affecting change — your `updatedSince` cursor.

Quantities & money

API field	Type	Nullable	Semantics
`miles`	decimal string	yes	Load miles.
`totalCost`	decimal string	yes	The invoice amount for the load (your all-in cost).

Status

status is a closed list — these exact values and no others will ever appear. Some are freight-ops jargon, so here's the plain-English gloss:

Value	Plain English
`PrePlanning`	Booked with us, but not yet scheduled.
`Available`	Scheduled; carrier not yet assigned.
`Covered`	Carrier assigned; driver not yet assigned.
`Dispatched`	Driver assigned and confirmed.
`Loading`	Driver is at the pickup site.
`InTransit`	Rolling — left the pickup site.
`Unloading`	Driver is at the delivery site.
`Delivered`	Freight is off the truck.
`Claims`	Damage/loss issue under review.
`PenApp`	Delivered; billing approval pending.
`Completed`	Billed and closed — terminal.
`OnHold`	Paused by operations (can happen from any state).
`Cancelled`	Cancelled (can happen from any state).

One deliberate quirk: the customer portal UI groups these into friendlier buckets ("Tendered", "In-transit", "Delivered"). The API returns the raw operational vocabulary above — richer, but different words. If you display statuses to end users alongside portal access, map them yourself or expect the mismatch.

What the API does not provide

Being upfront so you don't burn time looking for these:

PFF / additional-cost line items — totalCost is the single all-in figure. A cost breakdown (fuel component, accessorials) is under evaluation as a follow-up; ask your account contact if you need it and we'll prioritize accordingly.
Carrier, driver, and equipment details — not part of this API's scope.
Documents (POD, BOL) — not available via API today.
Internal economics (our carrier cost, margin) — never.