API reference - Public Overview
FreightForge Carrier Data API
REST API for accessing the FreightForge verified carrier dataset. This page covers endpoints, authentication, field schema, webhooks, rate limits, and error codes. Contact FreightForge to request API access.
Base URL api.freightforge.com/v1
Authentication: API key (HMAC-signed)
Response format: JSON
API version v1: current
Overview
What you can build with the FreightForge API
The FreightForge REST API provides programmatic access to a dataset of 200,000+ available pieces of capacity that has been verified against FMCSA records and enriched with location-zone and lane data. It is designed for integration into TMS platforms, 3PL compliance systems, and freight technology products.
The API is versioned, JSON-first, and authenticated with an API key - either a simple bearer token or, for production tiers, an HMAC-signed request. All endpoints are served over HTTPS only.
What this public reference covers
This page documents the public API overview — endpoints, field schema, webhook events, rate limits, and error codes. It is intentionally complete enough for a technical evaluation. Full integration support and credentials are provided through the FreightForge onboarding process.
Authentication
Client credentials
Every request authenticates with an API key issued to your account. The Free tier accepts a simple bearer token. Basic and higher tiers require each request to be HMAC-signed, which protects against replay and tampering. There are no login or token-refresh round-trips - you sign each request directly.
Token requestcopy
GET /v1/carriers/usdot/3506070
Host: api.freightforge.com
X-FF-Api-Key: ffk_your_api_key
X-FF-Timestamp: 1733500800
X-FF-Signature:
3a7bd3e2c9f1...
Token response
# string to sign
timestamp +
"." + method + "." + route + "." + sha256(body)
# route
= the path you called
/v1/carriers/usdot/3506070
X-FF-Signature = HMAC-SHA256(secret,
string)
For bearer authentication (Free tier), pass your key in the Authorization: header:Authorization: Bearer {api_key}.
Signing a request
For HMAC authentication, send three headers with every request: X-FF-Api-Key (your key), X-FF-Timestamp (current Unix time, valid for a 5-minute window) and X-FF-Signature. The signature is HMAC-SHA256 of your API secret over the string timestamp.method.route.sha256(body), where route is the path you called, beginning /v1. Access to specific endpoints and to bulk export is governed by your subscription tier, not by request scopes.
Making requests
Base URL, headers, and response structure
All API requests are made over HTTPS to the base URL below. Every request must be authenticated - a bearer token in the Authorization header on the Free tier or an HMAC signature on Basic and above.
Base URL
https://api.freightforge.com/v1 — prefix all endpoint paths with this URL. The version segment is included in every path. Prior versions remain available for a minimum of 12 months after a new version is released.
Required headers
X-FF-Api-KeyHMAC
Your API
key. Required on HMAC-authenticated requests.
X-FF-TimestampHMAC
Current
Unix timestamp. Requests must arrive within a 5-minute window.
X-FF-SignatureHMAC
HMAC-SHA256 signature of the request. See
Authentication.
AuthorizationFree tier
Format: Bearer {api_key}. Simple bearer auth, Free tier
only.
Content-TypePOST only
Must be application/json for POST request bodies.
Minimal working request
curl examplecopy
curl -X GET
https://api.freightforge.com/v1/carriers/usdot/3506070
-H "Authorization: Bearer ffk_your_api_key"
200 OK — response envelope
{
; "data": { /*
carrier object */ }
}
// X-Request-ID and X-RateLimit-* are returned as response
headers
Pagination
List endpoints return paginated results. Use page and per_page query parameters to navigate.
Paginated response envelope
{
; "data": [ /*
array of carrier objects */ ],
"meta":
{
"total": 4820,
"page": 1, "per_page": 25, "total_pages": 193,
"has_more": true,
"filters": { /* echo of
applied filters */ }
}
}
pageinteger
Page
to retrieve. Starts at 1. Default: 1.
per_pageinteger
Results per page. Default: 25. Max:
100.
has_moreresponse
Boolean in meta. True when more pages remain — use it to detect end of
results.
Errors
HTTP status codes and error format
All errors return a JSON body with a machine-readable code and a human-readable message. The code field is stable across API versions; message is for debugging only and may change.
Error response format
{
; "code": "not_found",
"message": "Carrier not found with USDOT:
9999999"
}
400invalid_payloadMalformed request body or a missing/invalid
parameter. The message field names the problem.
401unauthorizedMissing or invalid API key or HMAC signature, or a
timestamp outside the 5-minute window.
403tier_access_deniedThis endpoint is not available on your
subscription tier, or the carrier is outside your permitted source.
404not_foundNo carrier in the FreightForge dataset matches the
provided USDOT or MC number.
429rate_limit_exceededRate limit exceeded. The Retry-After response
header gives the seconds to wait before retrying.
Rate limits
Per-plan request limits
Rate limits are enforced per API key, per hour and per day - not per minute.Every response carries X-RateLimit-Limit-Hour, -Remaining-Hour, -Limit-Day, Remaining-Day and -Reset headers. The Free evaluation tier
allows 100 requests/hour. Bulk lookup requests count as 1 request regardless of batch size."
Basic
1,000 / hr
10,000 / day
Professional
5,000 / hr
50,000 / day
Enterprise
25,000 / hr
250,000 / day
Bulk lookup rate weighting
A single POST /v1/carriers/lookup request with 100 identifiers counts as 1 request against your rate limit, not 100. This makes batch operations significantly more efficient than individual lookups for database audits and bulk verification workflows.
Endpoints
Carrier data endpoints
GET
/v1/carriers/usdot/{usdot_number}
Returns a single verified carrier profile by USDOT number, including all available fields - authority status, insurance, safety rating, equipment, power units, headquarters and lane zones, and verification metadata. A companion lookup by internal ID is available at /v1/carriers/{id}.
Path parameter
usdot_numberrequiredThe
carrier's USDOT number. Returns all available fields; there is no field-subset parameter on reads.
GET
/v1/carriers
Paginated, compliance-gated list of carriers with rich filtering — by location, fleet size, equipment, proximity, and zone. Every carrier is returned with its full field set. Results are ordered by most recently updated, or nearest-first when a proximity radius is supplied.
Query parameters
searchstringCompany name, USDOT, or MC number.
state, countrystringState/province (e.g. TX) and country.
min_power_units, max_power_unitsintegerFleet size range.
equipmentstringComma-separated equipment tokens (van, reefer, flatbed, and more). Add equipment_match_all=1 to require all.
lat, lng, radiusnumberProximity search in miles. Returns distance_miles, nearest first.
zonestringHeadquarters zone (zone_0 through zone_9, canada_zone_western/central/eastern).
origin_zone, destination_zonestringCarriers running a lane from or to a zone. Both together match one origin-to-destination lane.
modified_sincedatetimeOnly carriers modified after this timestamp.
page, per_pageintegerPagination. per_page max 100, default 25.
POST
/v1/carriers/lookup
Batch carrier lookup. Submit up to 100 USDOT or MC numbers in a single request. Prefix MC numbers with MC-; a bare number is treated as a USDOT. Returns a verified profile or a structured error for each input, in the same order as the input array. Ideal for auditing an existing carrier database.
Body
identifiersrequiredarrayMC or DOT strings. Max 100.
id_typestringmc | dot | auto. Default auto.
fieldsstringComma-separated subset.
POST
/v1/export
Triggers an asynchronous bulk export of filtered carrier data. Returns an export_id immediately; poll GET /v1/export/{export_id} for status and download the file when complete. The request body accepts the same filters as GET /v1/carriers, plus an optional fields array to select specific columns. Available on Professional and above.
Body
filtersobjectSame keys as GET /v1/carriers
formatstringjson | csv. Default json.
fieldsstringComma-separated subset.
callback_urlstringWebhook URL when ready. Optional.
Data reference
Carrier object — selected fields
The carrier object contains up to 143 fields. Only fields that have a value are returned, so the exact set varies by carrier - a typical carrier returns around 90. Nineteen core identity and status fields are present on every carrier. A selection of key fields is documented below; contact the FreightForge team for the complete field reference.
FMCSA auto-populated
System-generated
Carrier-submitted
| Field | Type | Source | Description |
|---|---|---|---|
| usdot_number | string | FMCSA | USDOT number |
| mc_number | string | FMCSA | MC / docket number |
| carrier_legal_name | string | FMCSA | Legal business name |
| usdot_status | string | FMCSA | Active or Inactive |
| allowed_to_operate | string | FMCSA | Yes or No |
| state_province, city | string | Carrier | Physical location |
| company_location_zone | string | System | Headquarters zone |
| number_of_power_units | integer | Carrier | Fleet size |
| equipment | array | Carrier | Equipment tokens |
| origin_zones, destination_zones | array | System | Lane zones served |
| safety_rating | string | FMCSA | e.g. Satisfactory |
| number_of_oos_events | integer | FMCSA | Out-of-service events |
| liability_amount, cargo_amount | string | FMCSA | Insurance on file |
| insurance_company_name | string | FMCSA | Insurer |
| CSA BASIC scores | object | FMCSA | Percentile scores across 7 BASIC safety categories |
Full field reference
The complete reference — all 143 fields with types and value notes — is available on request.
Contact the FreightForge team for the full field reference and integration support during onboarding.
Data reference
Zone schema
The origin_zones and destination_zones fields return arrays of zone tokens. Zones are also accepted as filters on GET /v1/carriers: zone filters by the carrier's headquarters zone, while origin_zone and destination_zone filter by the lanes a carrier runs. The 13 zones below are the complete set of valid tokens; an unrecognized token is ignored.
zone_0
Zone 0
CT, MA, ME, NH, NJ, RI, VT
zone_1
Zone 1
DC, DE, NY, PA
zone_2
Zone 2
MD, NC, SC, VA, WV
zone_3
Zone 3
AL, FL, GA, MS, TN
zone_4
Zone 4
IN, KY, MI, OH
zone_5
Zone 5
IA, MN, MT, ND, SD, WI
zone_6
Zone 6
IL, KS, MO, NE
zone_7
Zone 7
AR, LA, OK, TX
zone_8
Zone 8
AZ, CO, ID, NM, NV, UT, WY
zone_9
Zone 9
AK, CA, OR, WA
canada_zone_central
Canada - Zone Central
ON, QC
canada_zone_eastern
Canada - Zone Eastern
NB, NL, NS, PE
canada_zone_western
Canada - Zone Western
AB, BC, MB, SK
Multiple zones per carrier
A carrier can serve multiple origin and destination zones. zone=zone_5 matches carriers headquartered in Zone 5. origin_zone=zone_5 matches any carrier running a lane originating in Zone 5, and destination_zone=zone_7 any carrier with a lane ending in Zone 7. Supplying both matches a single origin-to-destination lane.
Data reference
Equipment type
The equipment field returns an array of equipment tokens. These same tokens are accepted as filter values on GET /v1/carriers?equipment={token}. The table below lists all valid tokens.
| Value | Label | Description |
|---|---|---|
| van | Van | Standard dry van trailer |
| reefer | Reefer | Refrigerated trailer |
| flatbed | Flatbed | Open flatbed trailer |
| cargo | Cargo | Enclosed cargo van |
| straight_truck | Straight Truck | Single-unit box truck |
| box_truck | Box Truck | Box / cube truck |
| hotshot | Hotshot | Hotshot / expedited |
| power_only | Power Only | Tractor without trailer |
| sprinter | Sprinter | Sprinter van |
| rgn_trailer | RGN Trailer | Removable gooseneck |
| specialized_trailer | Specialized Trailer | Specialized / oversize |
| lowboy_trailer | Lowboy Trailer | Lowboy / heavy haul |
| stepdeck_trailer | Step Deck Trailer | Step deck / drop deck |
| hopper | Hopper | Hopper bottom |
| car_hauler | Car Hauler | Auto transport |
Multiple equipment types per carrier
Carriers can list multiple equipment types. Filtering with GET /v1/carriers?equipment=reefer returns any carrier whose equipment array contains reefer. To filter by multiple types, pass a comma-separated list: equipment=van,reefer returns carriers running either type. Add equipment_match_all=1 to require all listed types instead.
Webhooks
Event types and payload format
Subscribe to carrier profile change events by registering a webhook endpoint. FreightForge delivers an HTTP POST to your endpoint shortly after a qualifying event. Delivery is at-least-once — your endpoint must be idempotent.
Event types
Available events
carrier.createdA new carrier is added to the directory
carrier.updatedA carrier profile data field changes
carrier.status_changedA carrier authority or operating status changes
carrier.insurance_changedA carrier insurance on file changes
Example payload
carrier.status_changed
{
"event": "carrier.status_changed",
"timestamp": "2026-06-25T14:22:00Z",
"data": {
"usdot_number": "3506070",
"usdot_status": "Inactive"
}
}
Retry behavior
If your endpoint returns a non-2xx response or times out, FreightForge retries with backoff: 1 min, 5 min, 15 min, 1 hr, 4 hr. After 5 failed attempts the event is marked undelivered.