Home → Blog

Accelerating carrier onboarding is one of the most leverage-rich upgrades a 3PL can make. Yet most teams still stitch together manual lookups (FMCSA, FMC, Google, stale spreadsheets), copy/paste safety ratings out of SAFER, bounce between portals to check fuel surcharges, and ask ops to “eyeball” port conditions that could derail handoffs. The result is slow onboarding, missed SLAs, inconsistent compliance, and fragmented data trails that can’t stand up to audits.

This post shows how to build API-driven carrier validation flows that are fast, auditable, and production-ready using FreightPulse. FreightPulse consolidates the logistics intelligence you actually need—US FTL quotes, EIA fuel prices, FMCSA and FMC lookups, IMF PortWatch congestion, and natural-disruption alerts—into one REST API with a single response shape. You’ll see how to turn multi-hour onboarding checks into a few seconds of automated validation, with the exact fields an ops analyst, TMS, or compliance bot requires to greenlight a carrier.

We’ll walk through practical requests, complete JSON responses, field-by-field interpretations, and production tips. By the end, you’ll have a working pattern you can plug into your 3PL onboarding flow to verify carriers, estimate fuel surcharges, detect regional risks, and route freight with confidence—without juggling five different integrations.

Why FreightPulse

FreightPulse brings the core operational signals for a modern 3PL behind one consistent REST layer. Instead of wiring EIA for fuel, Warp (or other providers) for US FTL quotes, IMF PortWatch for congestion, FMCSA/FMC for carrier verification, and multiple hazard feeds for natural disruptions, you query a single API and receive a uniform response envelope you can parse once and reuse across services.

Bottom line: With FreightPulse, a new carrier can be validated for identity, safety posture, and environmental context in seconds using consistent JSON, and your TMS or onboarding portal can store the resulting artifacts for later audit.

Quick Start

FreightPulse is a standard JSON-over-HTTPS REST API. You can explore it from a terminal with curl or from code using your preferred HTTP client. The base URL for all requests is: 

https://freightpulsehq.com/api/v1

Below is a first request to fetch current US diesel and gasoline prices with regional breakdowns and short historical context. This is immediately useful for computing a fuel surcharge baseline during onboarding. 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/fuel-prices"

Example JSON response and what it means: 

{
"success": true,
"data": {
"timestamp": "2026-07-30T12:00:00Z",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 3.847,
"change_week": -0.023,
"change_percent": -0.6,
"regions": {
"east_coast": 3.912,
"midwest": 3.756,
"gulf_coast": 3.623,
"rocky_mountain": 3.891,
"west_coast": 4.456,
"california": 4.892
},
"historical": {
"30d_avg": 3.82,
"90d_avg": 3.75,
"yoy_change_percent": -8.2
}
},
"gasoline": {
"national_average": 3.156,
"historical": {
"30d_avg": 3.1,
"90d_avg": 3.05,
"yoy_change_percent": 1.1
}
}
}
}
}

Key fields you’ll use:

Core Endpoints

1) /carriers — FMCSA trucking and FMC ocean verification

Carrier identity and compliance are the first blockers in any onboarding flow. With /carriers, you can look up US trucking carriers via FMCSA SAFER data, or validate ocean NVOCC/OTI registrations from the FMC directory. These are the canonical sources you need to prevent identity mix-ups and confirm operational status.

Endpoint: 

GET /carriers

Key params:

Try a common US trucking carrier DOT number: 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/carriers?q=54283"

Sample response: 

{
"success": true,
"data": {
"type": "trucking",
"query": "54283",
"results": [
{
"dot_number": 54283,
"legal_name": "SWIFT TRANSPORTATION COMPANY OF ARIZONA LLC",
"status": "active",
"safety_rating": "S",
"drivers": 12883,
"address": {
"city": "Phoenix",
"state": "AZ",
"country": "US"
}
}
]
}
}

How to use it:

If you need to validate an ocean NVOCC/OTI: 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/carriers?q=APL%20LOGISTICS&type=ocean"

Ocean responses return FMC-registered entities when available, enabling you to extend the same onboarding playbook to your ocean partners.

2) /fuel-prices — EIA-driven surcharge intelligence

Fuel surcharge arguments often derail great carrier relationships. Use /fuel-prices to anchor negotiations and automate surcharge updates with transparent, authoritative indices. You’ll reduce manual spreadsheet churn and keep customers, carriers, and finance aligned.

Endpoint: 

GET /fuel-prices

No parameters are required. See Quick Start for a complete example response. For historical series tuned for charts and audits, use /historical (below).

Practical tips:

3) /freight-rates — Live US FTL quotes for spot checks and benchmarking

Once a carrier clears identity and safety gates, sanity-check their rate card against a real-time market reference. /freight-rates returns live FTL quotes for US trucking lanes (via Warp) in the same JSON envelope format you already parse elsewhere.

Endpoint: 

GET /freight-rates

Key params (trucking):

Example request: 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210"

Example response: 

{
"success": true,
"data": {
"mode": "trucking",
"service": "FTL (53' dry van)",
"source": "Warp",
"price_usd": 7207.92,
"transit_days": 4,
"pickup_date": "2026-08-24",
"delivery_date": "2026-08-28"
}
}

Interpreting the fields:

Note: If required parameters are missing, you’ll receive a 200 with "available": false in data rather than an error, which you can treat as a soft validation failure in your onboarding UI.

4) /port-congestion — Lagged congestion baseline for risk-aware routing

Port conditions shape downstream trucking reliability. /port-congestion returns a 7-day average of port calls versus a 90-day baseline (a lagged approximation ~6–7 days, not live AIS). That’s perfect for trend-aware routing and onboarding risk annotations, without paying for raw AIS feeds.

Endpoint: 

GET /port-congestion

Key params:

Example: 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

Example response: 

{
"success": true,
"data": {
"results": [
{
"port": "Los Angeles-Long Beach",
"locode": "US LAX",
"country": "United States",
"congestion": "moderate",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 8.7,
"baseline_avg_portcalls_per_day": 10.2,
"ratio_vs_baseline": 0.85
}
}
]
}
}

What to do with it:

5) /disruptions — Natural hazard awareness near ports and in-country

Driver safety and ETAs hinge on what the weather and earth are doing. /disruptions consolidates signals from GDACS, USGS, and NOAA/NWS—cyclones, earthquakes, floods, wildfires, volcanoes, drought, severe weather—so your onboarding process can flag location-sensitive risks for a carrier’s primary lanes.

Endpoint: 

GET /disruptions

Key params:

Example: 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"

Example response: 

{
"success": true,
"data": {
"results": [
{
"id": "gdacs:TC:1001305",
"type": "cyclone",
"severity": "moderate",
"title": "Tropical Cyclone SAUDEL-26",
"country": "Japan",
"starts_at": "2026-08-18T12:00:00+00:00",
"source": "GDACS"
}
]
}
}

How to use:

6) /historical — Time series for dashboards and audit trails

Historical visibility cements trust: procurement wants to see last month’s diesel curve; ops wants to see how congestion evolved at Long Beach; finance wants a clean audit chain. /historical returns either weekly national fuel-price series or daily port-congestion series for ~20 curated major ports.

Endpoint: 

GET /historical

Key params:

Example (diesel, 30d): 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_national&period=30d"

Response: 

{
"success": true,
"data": {
"metric": "fuel_price_diesel_national",
"period": "30d",
"series": [
{
"date": "2026-07-27",
"value": 5.257
},
{
"date": "2026-08-03",
"value": 5.343
}
]
}
}

Usage patterns:

End-to-End Onboarding Blueprint Using FreightPulse

Let’s put the endpoints together in a practical 3PL onboarding flow:

  1. Identity and safety gate: Query /carriers with the submitted DOT or name. Fail closed if status != active or safety_rating indicates risk outside policy. Persist legal_name, dot_number, safety_rating, and drivers.
  2. Fuel surcharge alignment: Call /fuel-prices to capture the current diesel reference and compute your program’s surcharge band (e.g., per $0.05 above a baseline). If your program is region-weighted, leverage the regions map or pull /historical to smooth with 30d averages.
  3. Market sanity check: With the carrier’s representative lane pairings, request /freight-rates for 2–3 lanes. If proposed rates are materially off-market, flag for procurement review or request SLA justification.
  4. Contextual risk notes: If the carrier’s lanes are port-connected, consult /port-congestion for those ports and store the as_of, congestion classification, and ratio_vs_baseline. If there are active /disruptions near those ports or in their primary states, attach the event id and severity.
  5. Finalize and archive: Record all API responses with timestamps in the carrier’s onboarding packet. This creates an auditable, repeatable, and automated process that reduces manual effort and speeds carrier time-to-first-load.

Complete, Realistic JSON Examples You Can Paste Into Tests

Use the following samples to stub contract tests and to validate your parsing and error paths. They mirror real FreightPulse responses, including the unified success/data/error envelope.

Fuel prices (national + regions) 

{
"success": true,
"data": {
"timestamp": "2026-07-30T12:00:00Z",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 3.847,
"change_week": -0.023,
"change_percent": -0.6,
"regions": {
"east_coast": 3.912,
"midwest": 3.756,
"gulf_coast": 3.623,
"rocky_mountain": 3.891,
"west_coast": 4.456,
"california": 4.892
},
"historical": {
"30d_avg": 3.82,
"90d_avg": 3.75,
"yoy_change_percent": -8.2
}
},
"gasoline": {
"national_average": 3.156,
"historical": {
"30d_avg": 3.1,
"90d_avg": 3.05,
"yoy_change_percent": 1.1
}
}
}
}
}

Carrier lookup (FMCSA trucking) 

{
"success": true,
"data": {
"type": "trucking",
"query": "54283",
"results": [
{
"dot_number": 54283,
"legal_name": "SWIFT TRANSPORTATION COMPANY OF ARIZONA LLC",
"status": "active",
"safety_rating": "S",
"drivers": 12883,
"address": {
"city": "Phoenix",
"state": "AZ",
"country": "US"
}
}
]
}
}

Live US FTL quote 

{
"success": true,
"data": {
"mode": "trucking",
"service": "FTL (53' dry van)",
"source": "Warp",
"price_usd": 7207.92,
"transit_days": 4,
"pickup_date": "2026-08-24",
"delivery_date": "2026-08-28"
}
}

Port congestion (lagged, 7d average vs 90d baseline) 

{
"success": true,
"data": {
"results": [
{
"port": "Los Angeles-Long Beach",
"locode": "US LAX",
"country": "United States",
"congestion": "moderate",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 8.7,
"baseline_avg_portcalls_per_day": 10.2,
"ratio_vs_baseline": 0.85
}
}
]
}
}

Disruptions near a port 

{
"success": true,
"data": {
"results": [
{
"id": "gdacs:TC:1001305",
"type": "cyclone",
"severity": "moderate",
"title": "Tropical Cyclone SAUDEL-26",
"country": "Japan",
"starts_at": "2026-08-18T12:00:00+00:00",
"source": "GDACS"
}
]
}
}

Error Handling and Production-Ready Patterns

FreightPulse replies include explicit HTTP status codes and a consistent JSON body, which makes it straightforward to implement resilient clients.

Example of a defensive JavaScript fetch wrapper for unified parsing: 

async function fpGet(path, params = {}) {
const qs = new URLSearchParams(params).toString();
const url = `https://freightpulsehq.com/api/v1/${path}${qs ? "?" + qs : ""}`;
const res = await fetch(url, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const body = await res.json();
if (!res.ok || body.success === false) {
const message = body && body.error ? body.error : `HTTP ${res.status}`;
throw new Error(message);
}
return body.data;
}

// Example: safety-gate a DOT number
(async () => {
try {
const data = await fpGet("carriers", { q: "54283" });
const result = data.results[0];
if (!result || result.status !== "active") {
console.warn("Carrier not active; routing to manual review.");
} else {
console.log(`OK: ${result.legal_name}, rating ${result.safety_rating}`);
}
} catch (err) {
console.error("Lookup failed:", err.message);
}
})();

Real-World Use Cases

1) Automated carrier vetting tool for a 3PL onboarding portal

When a carrier submits a DOT number, your portal calls /carriers to validate legal_name, status, safety_rating, and drivers. If status != active or the rating violates policy, the system blocks approval and outputs a clear remediation path. Pair with /disruptions scoped to the carrier’s hub states to flag near-term weather risks in an onboarding note for dispatchers.

Endpoints used: /carriers, /disruptions.

2) Fuel-surcharge calculator embedded in rate confirmation

Build a widget that calls /fuel-prices for the current diesel national_average and regional indices, and /historical for a 30d average. Your formula can weight regions by lane mix, stabilize volatility with 30d_avg, and stamp the final multiplier into the confirmation so finance and customers see the exact index used on the approval date.

Endpoints used: /fuel-prices, /historical.

3) Port-aware onboarding scorecard for ocean-connected lanes

If a brokerage onboards a drayage partner or a TL carrier supporting a port, query /port-congestion with the relevant LOCODE and pull the current congestion classification and ratio_vs_baseline. Show a traffic-light indicator and a short recommendation (e.g., “Moderate congestion: add 0.5 day buffer”). Add a /disruptions query near that port to catch cyclones or severe weather looming within the week.

Endpoints used: /port-congestion, /disruptions.

Practical Implementation Guide: From Prototype to Production

To stand up a robust onboarding service, keep these implementation details in mind:

Here is a concise Python example that unifies three checks—carrier, fuel, and a market quote—into one flow: 

import requests

BASE = "https://freightpulsehq.com/api/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}

def fp_get(path, params=None):
r = requests.get(f"{BASE}/{path}", headers=HEADERS, params=params or {}, timeout=20)
r.raise_for_status()
body = r.json()
if not body.get("success", False):
raise RuntimeError(body.get("error", "Unknown error"))
return body["data"]

def vet_carrier(dot_or_name, lane):
# 1) Identity & safety
carriers = fp_get("carriers", {"q": dot_or_name})
result = carriers.get("results", [None])[0]
if not result:
return {"ok": False, "reason": "No carrier found"}
if result.get("status") != "active":
return {"ok": False, "reason": "Carrier not active", "carrier": result}

# 2) Fuel baseline
fuel = fp_get("fuel-prices", {})
diesel = fuel["data"]["diesel"]
fuel_baseline = diesel["national_average"]

# 3) Market sanity check
rates = fp_get("freight-rates", {
"mode": "trucking",
"origin_zip": lane["origin_zip"],
"destination_zip": lane["destination_zip"]
})

return {
"ok": True,
"carrier": result,
"fuel_usd_per_gal": fuel_baseline,
"quote_price_usd": rates.get("price_usd"),
"transit_days": rates.get("transit_days")
}

print(vet_carrier("54283", {"origin_zip": "10001", "destination_zip": "90210"}))

Endpoint-by-Endpoint Deep Dive: Parameters, Fields, and Best Practices

/carriers

/fuel-prices

/freight-rates

/port-congestion

/disruptions

/historical

Security, Reliability, and Observability Practices for Logistics APIs

Production onboarding pipelines deserve the same rigor as your order ingestion path. Apply these patterns when integrating FreightPulse:

FAQ

How often do FreightPulse fuel prices update?

Diesel and gasoline data reflect EIA series, which typically update weekly for diesel. You can safely cache responses daily or until the next expected EIA publication. Use the timestamp field in the response to record the reference time used in your onboarding calculations.

Can I look up ocean carriers as well as trucking carriers?

Yes. The /carriers endpoint supports both trucking (FMCSA SAFER) and ocean NVOCC/OTI (FMC directory) lookups via the type parameter. Provide either a name or an appropriate identifier and parse the results array for your match.

Does the port congestion data reflect real-time vessel wait times?

No. /port-congestion provides a lagged approximation: a 7-day average of port calls against a 90-day baseline with a data lag around 6–7 days. It is best used for trend and planning context, not as a live queue length or same-day operational feed.

What hazards are included in disruptions, and can I filter by port proximity?

/disruptions consolidates natural hazards only—cyclones, earthquakes, floods, volcanoes, drought, wildfires, and severe weather—from GDACS, USGS, and NOAA/NWS. You can filter by country and by port proximity; port filters generally apply a 300km radius (100km for US weather), ideal for early warnings tied to specific gateways.

How should I handle missing parameters or invalid inputs?

Validate required parameters client-side to avoid 422 errors. Some endpoints, such as /freight-rates, return HTTP 200 with data.available=false when required lane parameters are missing—treat this as a soft validation failure and prompt users to complete the form.

Conclusion + CTA

Carrier onboarding is a mission-critical workflow that deserves automation, context, and auditability. With FreightPulse, you can verify identity and safety, anchor surcharge logic with authoritative fuel indices, sanity-check rates with live market quotes, quantify port trends, and flag natural hazards—using one consistent API. Your team ships faster, your decisions are traceable, and your operators spend less time tab-hopping and more time serving customers.

The fastest path from a spreadsheet-driven onboarding checklist to a production-grade, API-driven flow starts with a single integration. Wire in /carriers to eliminate identity uncertainty, plug in /fuel-prices and /historical to stabilize surcharges, use /freight-rates to benchmark bids, and enrich with /port-congestion and /disruptions for resilient planning. You’ll cut hours of manual work per carrier, improve compliance, and build trust across stakeholders with data-backed decisions.

Build your first automated validation in an afternoon. Explore the endpoints, paste the examples above into your tests, and start instrumenting your onboarding pipeline with live logistics intelligence. Visit FreightPulse to learn more, and Try FreightPulse for free to accelerate your next carrier onboarding cycle.