Home → Blog

Spot contracts move fast, and when a 3PL or logistics operator needs to arbitrate a dispute—wrong rate applied, fuel surcharge mismatch, missed pickup due to a storm, or inflated detention claims—the hardest part is assembling clean evidence quickly. By the end of this post you’ll know how to design automated dispute detection, build time-stamped evidence bundles, and run resolution workflows using a single API: pulling live FTL quotes, verified fuel price indices, port congestion context, carrier verifications, and natural-disruption alerts from FreightPulse.

Introduction

Disputes around spot moves often come down to “what was true at the time”: the market linehaul rate, the official diesel index driving the FSC, the carrier’s status, and whether a natural event reasonably caused a schedule slip. The longer it takes to assemble those facts, the more likely you’ll write off margin or damage a carrier/buyer relationship.

This tutorial shows how to wire up dispute automation with FreightPulse: detect anomalies (rate spike vs. baseline), fetch authoritative fuel indices for surcharge validation, check a carrier’s FMCSA status, gather disruption context near a destination port, and store everything in a structured evidence bundle. Because FreightPulse consolidates those feeds behind one REST interface, you won’t have to stitch five different integrations just to get to a defensible answer.

We’ll cover a quick start, the endpoints you’ll rely on, example cURL and code, and the field-level details you’ll use to build production-grade arbitration workflows for your TMS or internal tooling.

Why FreightPulse

Quick Start

Base URL:

https://freightpulsehq.com/api/v1

Authentication: Send your key in the X-API-Key header. Unauthenticated requests are allowed in small volumes, but for production arbitration flows you should authenticate and handle error codes predictably.

First request: fetch national fuel prices to validate a disputed FSC (fuel surcharge) for a historical invoice period.

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

Illustrative JSON response (values shown here are example data from the API shape):

{
"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) Live FTL Freight Rates — benchmark the contracted quote

Endpoint: GET /freight-rates

Use this to fetch a contemporaneous benchmark for a disputed spot move. Compare the invoice linehaul to the returned price_usd for the same lane and pickup date. For trucking, pass origin_zip and destination_zip. Dates let you lock context to the day the contract was agreed.

Key params:

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

Example JSON (illustrative values per the provided schema):

{
"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"
}
}

Fields that matter for arbitration:

JavaScript example: calling /freight-rates and reading fields

<script>
async function fetchBenchmark() {
const url = "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210&pickup_date=2026-08-24";
const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const body = await res.json();
if (!body.success) throw new Error("Freight rates lookup failed");
const d = body.data;
// Attach to an evidence bundle in your system
return {
benchmark_mode: d.mode,
benchmark_service: d.service,
benchmark_price_usd: d.price_usd,
benchmark_transit_days: d.transit_days,
benchmark_pickup_date: d.pickup_date,
benchmark_delivery_date: d.delivery_date
};
}
fetchBenchmark().then(console.log).catch(console.error);
</script>

Tip: Cache the response you used to arbitrate. Store the full response JSON along with your internal dispute ID so the audit trail remains immutable.

2) Fuel Prices — validate the FSC

Endpoint: GET /fuel-prices

Fuel surcharge disputes usually hinge on which index and date apply. Use this endpoint to fetch the official EIA-derived diesel index (national and PADD regions) for the billing period and reference it directly in your FSC formula. Pair with /historical if you want a series to show an average over 30/90 days.

No required params.

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

Field notes for FSC calculation:

3) Port Congestion — contextual delay evidence

Endpoint: GET /port-congestion

When a spot move is delayed near a seaport (e.g., drayage handoff or port-adjacent cross-dock), you need context for whether congestion was elevated. This endpoint approximates port activity from IMF PortWatch AIS data: a 7-day average of port calls compared to a 90-day baseline. Data is lagged by roughly 6–7 days and is not live AIS tracking.

Key params:

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

Example JSON (illustrative values):

{
"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
}
}
]
}
}

Use cases in disputes:

4) Carrier Lookups — verify the carrier named in the dispute

Endpoint: GET /carriers

If a dispute references a carrier’s safety rating or claims they were inactive, you can verify via FMCSA SAFER for US trucking or FMC for ocean entities. For trucking, pass the DOT number or name in q. This is useful to validate that you tendered to a properly authorized carrier on the move date.

Key params:

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

Example JSON (illustrative values):

{
"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"
}
}
]
}
}

Evidence pointers:

5) Disruptions — natural hazards near a port or route

Endpoint: GET /disruptions

When a carrier cites weather or geophysical events, you can corroborate with active disruptions consolidated from GDACS, USGS, and NOAA/NWS. You can filter by type and severity or constrain by a port code to see events within a defined radius (300 km globally, with 100 km for US weather).

Key params:

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

Example JSON (illustrative values):

{
"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"
}
]
}
}

Attach the id, type, severity, and starts_at to your dispute record. Even when the event is not local to your lane, its presence can impact upstream schedules and ocean arrivals feeding port dray moves.

Designing Automated Dispute Detection

Here’s a practical pattern to flag spot contracts for review before they become contentious:

  1. Compute a lane benchmark at booking time with /freight-rates. If the invoiced linehaul deviates beyond a threshold (e.g., more than X% over the benchmark), queue the charge for manual or semi-automated review.
  2. When a shipment crosses a time window where EIA indices update, re-evaluate the FSC using /fuel-prices. If your contract keys to national_average or a PADD region, store both the index and the contract reference in your evidence store.
  3. For moves touching a curated port, pull /port-congestion to snapshot market context for the claim window. Note: congestion data is lagged ~6–7 days, reflecting a 7-day average vs a 90-day baseline—use it for trend context, not minute-by-minute ETAs.
  4. On claims citing weather delay, query /disruptions for the relevant port or corridor. Add any matching events to the bundle, including starts_at and severity.
  5. Verify the carrier with /carriers to confirm status and safety rating at the time of tender. Mismatches between the invoice carrier and the FMCSA legal entity are a common root cause in chargeback disputes.

Each detection rule appends standardized facts to an “evidence bundle” JSON document you store in your TMS or billing system. Because all FreightPulse responses share the same envelope and JSON-friendly fields, you can log the full API payload alongside your derived metrics.

Building Evidence Bundles

A lightweight evidence schema could look like this (your internal structure may vary):

{
"dispute_id": "DPT-2026-001234",
"contract": {
"mode": "trucking",
"origin_zip": "10001",
"destination_zip": "90210",
"pickup_date": "2026-08-24",
"invoice_linehaul_usd": 7650.00,
"invoice_fsc_usd": 325.00
},
"evidence": {
"freight_rates": {
"source_payload": { ... full /freight-rates JSON ... },
"benchmark_price_usd": 7207.92,
"transit_days": 4
},
"fuel_prices": {
"as_of": "2026-07-30T12:00:00Z",
"reference": "diesel.national_average",
"value_usd_per_gal": 3.847,
"source_payload": { ... full /fuel-prices JSON ... }
},
"port_congestion": {
"port": "US LAX",
"as_of": "2026-08-14",
"ratio_vs_baseline": 0.85,
"congestion": "moderate",
"source_payload": { ... full /port-congestion JSON ... }
},
"disruptions": [
{
"id": "gdacs:TC:1001305",
"type": "cyclone",
"severity": "moderate",
"starts_at": "2026-08-18T12:00:00+00:00"
}
],
"carrier": {
"dot_number": 54283,
"status": "active",
"safety_rating": "S",
"legal_name": "SWIFT TRANSPORTATION COMPANY OF ARIZONA LLC",
"source_payload": { ... full /carriers JSON ... }
}
}
}

In production, include the complete source_payload from each call. Keeping original API payloads makes your audit trail future-proof if your derived fields or business rules change later.

Resolution Workflows for 3PLs and Operators

Once your system builds an evidence bundle, you can streamline the resolution process:

cURL + JSON: One more example you can copy

For a historical trend chart to show adjudicators why your benchmark policy makes sense, pull a 30-day diesel series:

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

Example JSON (illustrative values):

{
"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 }
]
}
}

Use series to compute a rolling average or to annotate invoices that straddle index changes.

Practical Details You’ll Want

Real-World Use Cases

FAQ

How often do FreightPulse fuel prices update?

Fuel prices reflect EIA data and include a timestamp field so you can align with the correct reporting week. Use timestamp and the national_average or a regional value to match your contract’s FSC basis.

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

Yes. The /carriers endpoint supports trucking (FMCSA SAFER) by default, and ocean via the FMC directory when type=ocean. Pass q with the appropriate identifier or name for the directory you’re querying.

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

No. Port congestion uses an approximation derived from IMF PortWatch AIS data: a 7-day average compared to a 90-day baseline, with a data lag of about 6–7 days. Use it to add trend context to a dispute rather than minute-by-minute ETAs.

What happens if a required parameter is missing?

You’ll receive a structured error with success=false and an error message, or in the case of /freight-rates, an HTTP 200 indicating unavailability if lane params are incomplete. Always check the success flag and handle error codes like 401, 403, 422, and 429.

Can I try the API without a key during prototyping?

Yes. You can explore endpoints with unauthenticated requests in small volumes to validate your build. For production arbitration, include the X-API-Key header and store response payloads for audit.

Conclusion + CTA

Disputes are time-sensitive. The teams that win resolution speed do two things well: detect issues early and assemble facts instantly. With one API call each, you can capture a live lane benchmark, the authoritative diesel index, the port congestion context, any relevant natural disruptions, and the carrier’s status—then ship a single, time-stamped evidence bundle that stands up to review.

If you’re stitching together multiple data feeds—or if you’ve avoided adding context because it’s too time-consuming—centralizing on FreightPulse eliminates the integration overhead. It’s the fastest path from a disputed rate to a defensible answer your finance and carrier teams can agree on.

Try FreightPulse for free and wire these endpoints into your arbitration workflow today. Once your detection rules and evidence bundles are in place, your team will spend less time arguing numbers and more time closing the loop on profitable moves.