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. Sandbox access and the full OpenAPI specification are available after contacting the partner team.

Base URL api.freightforge.com/v1

Authentication: OAuth 2.0 bearer token

Response format: JSON

API version v1: current

Getting started

Overview Authentication Making requests Errors Rate limits

Endpoints GET /carriers/{usdot_number}GET /carriers POST /carriers/lookup GET /carriers/{usdot_number}/risk POST /export

Data reference

Carrier object Risk score enum Zone schema Equipment type

Webhooks

Event types Payload format Retry behavior

Sandbox + full spec

OpenAPI spec, sandbox keys, and error catalog require a partner account.

Request access →

Overview

What you can build with the FreightForge API

The FreightForge REST API provides programmatic access to a 30,000+ carrier dataset verified against FMCSA SAFER, scored for fraud risk, and enriched with lane and equipment data. It is designed for integration into TMS platforms, 3PL compliance systems, and freight technology products.

The API is versioned, JSON-first, and authenticated via OAuth 2.0 client credentials. All endpoints are available over HTTPS. There is no HTTP fallback.

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. The full OpenAPI specification (machine-readable, with all edge cases and error catalog), sandbox environment with 1,000 test carrier profiles, and integration support are available through the partner onboarding process.

Authentication

OAuth 2.0 client credentials

All API requests require a bearer token obtained via the OAuth 2.0 client credentials flow. Tokens are scoped to your environment (sandbox or production) and expire after 3,600 seconds. Refresh by re-running the token request.

Token requestcopy

POST https://auth.freightforge.com/oauth/token
Content-Type: application/x-www-form-urlencoded
 
grant_type=client_credentials
&client_id={your_client_id}
&client_secret={your_client_secret}
&scope=carriers:read

Token response

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "carriers:read"
}

Pass the token in the Authorization header on all subsequent requests: Authorization: Bearer {access_token}

Available scopes

carriers:read — read carrier profiles, search, and risk scores (3PL Access and above). carriers:write — create and update carrier profiles, trigger onboarding flows (TMS Partner and above). export:bulk — trigger async bulk exports (TMS Partner and above). webhooks:manage — create and manage webhook subscriptions (TMS Partner and above).

Making requests

Base URL, headers, and response structure

All API requests are made over HTTPS to the base URL below. Every request must include a valid bearer token in the Authorization header.

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

Authorizationrequired

Format: Bearer {access_token}. Tokens expire after 3,600 seconds.

Content-TypePOST only

Must be application/json for all POST request bodies.

Acceptoptional

Defaults to application/json. The API only returns JSON.

X-Request-IDoptional

Client-generated UUID returned in response headers. Useful for log correlation and support escalations.

Minimal working request

curl examplecopy

curl -X GET 
  https://api.freightforge.com/v1/carriers/MC-448821 
  -H "Authorization: Bearer {access_token}"

200 OK — response envelope

{
  "data": { /* carrier object */ },
  "meta": {
    "request_id": "req_01J3K8X...",
    "fmcsa_refreshed_at": "2026-06-25T06:00:00Z",
    "cache_age_seconds": null  // null = live data
  }
}

Pagination

List endpoints return paginated results. Use page and per_page query parameters to navigate.

Paginated response envelope

{
  "data": [ /* array of carrier objects */ ],
  "pagination": {
    "total": 4820,
    "page": 1, "per_page": 25, "total_pages": 193,
    "next_page": 2,  // null on last page
    "prev_page": null
  },
  "meta": { /* request_id, timestamps */ }
}

pageinteger

Page to retrieve. Starts at 1. Default: 1.

per_pageinteger

Results per page. Default: 25. Max: 100.

next_pageresponse

Next page number, or null on the last page. Use this to detect end of results rather than calculating from total.

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

{
  "error": {
    "code": "carrier_not_found",
    "message": "No carrier found with MC number MC-999999",
    "status": 404
  }
}

400invalid_requestMalformed request body or missing required parameter. Check the message field for the specific parameter.

401unauthorizedMissing or expired bearer token. Re-run the token request to obtain a fresh token.

403insufficient_scopeYour token does not include the required scope for this endpoint. Check your plan tier.

404carrier_not_foundNo carrier in the FreightForge dataset matches the provided MC or DOT number.

422fmcsa_unavailableFMCSA data temporarily unavailable. Response includes cached data where available, with a cache_age_seconds field.

429rate_limit_exceededRequest rate limit exceeded. The Retry-After response header contains seconds to wait before retrying.

500internal_errorUnexpected server error. Includes a request_id for support escalation. Transient — retry with backoff.

Rate limits

Per-plan request limits

Rate limits are enforced per API key per rolling 60-second window. The X-RateLimit-Remaining and X-RateLimit-Reset headers are returned on every response. Bulk lookup requests count as 1 request regardless of batch size.

3PL access

300 req/min

Read API only

TMS partner

1,000 req/min

Read + write API

Enterprise

Custom

Negotiated per contract

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_number}

Returns a single verified carrier profile by USDOT number. Includes all 64 data fields: authority status, insurance, safety rating, risk score, equipment types, lane data, and verification metadata. The fields parameter accepts a comma-separated list to return a subset of fields.

Parameters

usdot_numberrequiredstringUSDOT number with or without prefix

fieldsstringComma-separated field names. Omit to return all 64 fields.

include_lanesbooleanDefault true. Set to false to omit lane data.

GET

/v1/carriers

Paginated list of carrier profiles with filtering. Returns summary profiles by default (18 fields). Pass full=true to return complete 64-field records — this counts against rate limits at a higher weight. Results are sorted by risk score ascending (lowest risk first) by default.

Parameters

zonestringFilter by origin zone.

equipmentstringe.g. dry_van, reefer.

risk_scorestringlow | medium | high.

authority_statusstringactive | inactive. Default: active.

page / per_pageintegerDefault 1, 25/page. Max 100/page.

POST

/v1/carriers/lookup

Batch carrier lookup. Submit up to 100 MC or DOT numbers in a single request body. Returns a verified profile or a structured error for each input. Use for batch-auditing an existing carrier database. Responses are returned in the same order as the input array.

Body

identifiersrequiredarrayMC or DOT strings. Max 100.

id_typestringmc | dot | auto. Default auto.

fieldsstringComma-separated subset.

GET

/v1/carriers/{usdot_number}/risk

Returns only the risk scoring fields for a carrier - lightweight endpoint for compliance dashboards and real-time tender checks. Faster response time than the full carrier endpoint. Counts against rate limits at a lower weight than a full profile request.

Returns

risk_scorestringlow | medium | high

fmcsa_matchbooleanCross-validation pass/fail

ip_resultstringconsistent | unexpected_region | flagged

gps_scorestringplausible | elevated | flagged

verified_atstringISO 8601 timestamp

POST

/v1/export

Triggers an asynchronous bulk export of filtered carrier data. Returns a job_id immediately. Poll GET /v1/export/{job_id} for status. On completion, the response includes a pre-signed download URL valid for 24 hours. Available on TMS Partner plan and above. Scheduled exports (recurring, delivered to an S3 bucket or SFTP endpoint) available on Enterprise.

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 full carrier object contains 64 fields. Key fields are documented below. The complete field reference with all types, nullable notes, and enum values is available in the full OpenAPI specification.

FMCSA auto-populated

System-generated

Carrier-submitted

Field	Type	Source	Description
mc_number	string	FMCSA	MC number without prefix. Always present.
usdot_number	string	FMCSA	USDOT number. Always present.
legal_name	string	FMCSA	Legal company name as registered with FMCSA.
authority_status	string	FMCSA	Active \| Inactive \| Revoked
authority_granted_date	string	FMCSA	ISO 8601 date. Null if not yet granted.
insurance_current	boolean	FMCSA	Whether insurance on file is current at last refresh.
insurance_amount	integer	FMCSA	Coverage amount in USD. Null if not on file.
safety_rating	string	FMCSA	Satisfactory \| Conditional \| Unsatisfactory \| Unrated
risk_score	string	System	low \| medium \| high. Composite of three layers.
equipment_types	array	Carrier	Array of equipment type strings.
origin_zones	array	Carrier	Array of origin zone strings.
destination_zones	array	Carrier	Array of destination zone strings.
verified_at	string	System	ISO 8601 datetime of last verification run.
fmcsa_refreshed_at	string	System	ISO 8601 datetime of last FMCSA data pull.

Full field reference

All 64 fields, types, nullable notes, and enum values are in the full OpenAPI specification.

The spec is available in JSON and YAML. It includes all edge cases, null handling rules, and the complete error catalog. Issued alongside sandbox credentials after a partner onboarding call.

Request access →Schedule a partner call first

Data reference

Risk score enum

The risk_score field returns one of three string values on every carrier object and risk endpoint response. The score is a composite of three independent verification layers — FMCSA cross-validation, IP geolocation analysis, and GPS distance scoring. All three layers run on registration and re-run whenever FMCSA data changes.

"low"

Passed all three layers

FMCSA data matches registration, IP geolocation is consistent with operating address, and GPS distance is within plausible range for a road-based carrier.

Recommended handling

No action required. Safe to onboard and tender loads.

"medium"

One layer elevated

One verification layer returned an elevated signal - typically an IP region that doesn't match the operating state, or a GPS distance at the upper plausible threshold

Recommended handling

Surface a soft warning in your UI. Request additional verification before first load tender. Re-onboarding through FreightForge resolves most medium flags.

"high"

One or more layers flagged

At least one verification layer returned a hard flag - registration IP from outside North America, GPS distance implausible for a domestic carrier or FMCSA data mismatch on a critical field.

Recommended handling

Do not tender loads. Revoke access in your TMS. The carrier.fraud_flagged webhook fires on any transition to high.

Score recalculation

Risk scores recalculate automatically on any FMCSA data change for a carrier. They do not recalculate on a fixed schedule. If a carrier’s authority is reinstated or insurance is renewed, the score updates within one FMCSA refresh cycle (daily). Subscribe to carrier.risk_score_changed webhooks to receive immediate notification of tier changes.

What risk score does not expose

The specific thresholds used by each verification layer are not included in the API response or this documentation. The score tier and the layer results (ip_result, gps_score, fmcsa_match) are surfaced; the underlying scoring logic is not. This is intentional — threshold disclosure would allow bad actors to optimize registrations to pass verification.

Data reference

Zone schema

The origin_zones and destination_zones fields return arrays of zone strings. Zones are also accepted as filter parameters on GET /v1/carriers. The 13 zones below are the complete set of valid values, The API returns a 400 invalid_request error if an unrecognised zone string is passed as a filter.

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

mexico

Mexico

Cross-border Mexico lanes

Multiple zones per carrier

A carrier profile can have multiple values in both origin_zone and destination_zone. When filtering with GET /v1/carriers?zone=zone_5, results include any carrier whose origin zones array contains zone_5 — it does not need to be the only value. To filter by destination zone, use destination_zone=zone_5.

Data reference

Equipment type

The equipment_type field returns an array of equipment type strings. These same strings are accepted as filter values on GET /v1/carriers?equipment={type}. The table below lists all valid values.

Value	Label	Description
dry_van	Dry van	Standard enclosed trailer. Most common equipment type in the network.
reefer	Reefer	Temperature-controlled trailer. Includes both refrigerated and frozen capability.
flatbed	Flatbed	Open deck trailer. Includes standard 48ft and 53ft flatbeds.
step_deck	Step deck	Two-level deck for taller freight that exceeds standard flatbed height clearance.
power_only	Power only	Tractor without trailer. Used for drop-and-hook and shipper-owned trailer moves.
hotshot	Hotshot	Smaller expedited loads, typically on a medium-duty truck with a gooseneck trailer.
tanker	Tanker	Liquid or dry bulk tanker. Carriers must have tanker endorsement on FMCSA record.
lowboy	Lowboy	Heavy haul trailer for oversized or overweight equipment and machinery.
conestoga	Conestoga	Flatbed with a rolling tarp system. Combines flatbed access with weather protection.
double_drop	Double drop	Three-section trailer with two drops for maximum height clearance on heavy haul loads.
rgn	RGN (removable gooseneck)	Detachable gooseneck trailer that allows front loading of heavy equipment.
auto_carrier	Auto carrier	Vehicle transport trailer. Open or enclosed 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_types array contains reefer. To filter by multiple equipment types simultaneously, pass a comma-separated list: equipment=dry_van,reefer returns carriers who run either type.

Webhooks

Event types and payload format

Subscribe to carrier profile change events by registering a webhook endpoint via the API. FreightForge delivers an HTTP POST to your endpoint within 30 seconds of a qualifying event. Delivery is at-least-once — your endpoint must be idempotent.

Event types

Available events

carrier.authority_lapsedOperating authority revoked or allowed to lapse. Triggers immediately on FMCSA data change, not on scheduled refresh.

carrier.insurance_expiredInsurance on file has lapsed or coverage gap detected. Includes previous and new insurance status.

carrier.risk_score_changedComposite risk score tier changed — e.g. low → medium. Includes previous, new, and the triggering signal.

carrier.profile_updatedAny field changed on a scheduled FMCSA refresh. Payload includes a diff of changed fields only.

carrier.fraud_flaggedNew fraud signal detected. Flag type included in payload. Does not expose scoring thresholds.

Example payload

carrier.authority_lapsed

{
  "event": "carrier.authority_lapsed",
  "timestamp": "2026-06-25T14:22:00Z",
  "carrier_id": "MC-448821",
  "data": {
    "previous_status": "Active",
    "current_status": "Revoked",
    "effective_date": "2026-06-24"
  }
}

Retry behavior

If your endpoint returns a non-2xx response or times out (10-second limit), FreightForge retries with exponential backoff: 1 min, 5 min, 30 min, 2 hr, 8 hr. After 5 failed attempts, the event is marked undelivered and logged. You can replay undelivered events from the partner dashboard.