Skip to Content
FR8 Factory Docs

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 fieldTypeNullableSemantics
loadNumberstringnoFR8 Factory load number — the stable identity both parties quote. Upsert on this.
poNumberstringyesYour PO number, as entered on the load.
billingRefNumberstringyesYour billing reference, as entered on the load.

Origin & destination

API fieldTypeNullableSemantics
originCitystringyesPickup city.
originStatestringyesPickup state (2-letter).
originZipstringyesPickup ZIP.
originWarehousestringyesPickup warehouse name — populated only when the pickup stop is a warehouse we have on record; expect null for one-off addresses.
destinationCitystringyesDelivery city.
destinationStatestringyesDelivery state (2-letter).
destinationZipstringyesDelivery ZIP.
destinationWarehousestringyesDelivery 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 fieldTypeNullableSemantics
scheduledPickupDatedatetimeyesScheduled pickup appointment date.
scheduledPickupTimestringyesScheduled pickup appointment time (local, e.g. "08:00").
scheduledDeliveryDatedatetimeyesScheduled delivery appointment date.
scheduledDeliveryTimestringyesScheduled delivery appointment time (local).
tenderedDatedatetimeyesWhen the load was tendered to us.
actualPickupDatedatetimeyesDriver checked in at origin. null until pickup happens.
actualDeliveryDatedatetimeyesDriver checked in at destination. null until delivery happens.
requestedDeliveryDatedatetimeyesYour requested delivery date.
createdAtdatetimenoWhen the load was first created in FR8 Factory. Guaranteed non-null on every row — safe to key filters on. For loads that predate your data feed, this is the date the load was first imported, which may be later than the load's real-world creation.
updatedAtdatetimenoLast value-affecting change — your updatedSince cursor.

Quantities & money

API fieldTypeNullableSemantics
milesdecimal stringyesLoad miles.
totalCostdecimal stringyesThe 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:

ValuePlain English
PrePlanningBooked with us, but not yet scheduled.
AvailableScheduled; carrier not yet assigned.
CoveredCarrier assigned; driver not yet assigned.
DispatchedDriver assigned and confirmed.
LoadingDriver is at the pickup site.
InTransitRolling — left the pickup site.
UnloadingDriver is at the delivery site.
DeliveredFreight is off the truck.
ClaimsDamage/loss issue under review.
PenAppDelivered; billing approval pending.
CompletedBilled and closed — terminal.
OnHoldPaused by operations (can happen from any state).
CancelledCancelled (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.

Rate limits

Per-key limits, the response headers, and how to behave on 429.

Changelog

What changed in the Customer Data API, newest first.

On this page

Identity & referencesOrigin & destinationDates & scheduleQuantities & moneyStatusWhat the API does not provide
Help

How do I get API access?

API keys are issued per customer by the FR8 Factory team. Ask your account contact — or send us a request through the Help desk tab with your company name and use case.

How do I authenticate requests?

Send your API key in the Authorization header on every request. Keys are secret — never ship them in browser code or mobile apps.

Open the guide — How do I authenticate requests?

How do I keep my copy of the data in sync?

Use delta polling: request only records changed since your last sync cursor instead of re-downloading everything. The guide covers cursors, ordering, and replay safety.

Open the guide — How do I keep my copy of the data in sync?

What are the rate limits?

Limits are per API key and documented on the rate-limits page, along with the response headers that tell you where you stand and how to back off.

Open the guide — What are the rate limits?

What does each load field mean?

The load field dictionary defines every field the API returns — types, nullability, and freight-domain meaning (pick vs drop dates, AR, equipment types).

Open the guide — What does each load field mean?

Found a bug or missing data?

Send it through the Help desk tab with the request you made and what you expected back. You'll get a reference code, and we'll email you when it's resolved.