Home → Blog

Cross-border freight operations succeed or stall on the back of a thousand small handoffs. One of the most consequential is customs clearance: the exact moment a shipment flips from “inbound pending clearance” to “released” determines when drayage can stage, when a long-haul tender is sent, and how you avoid per diem and demurrage. Too often, those triggers are stitched together manually from emails, terminal PDFs, multiple data vendors, and time-consuming follow-ups — creating lags that ripple through docks, yards, and driver schedules.

This post shows how to automate those clearance-adjacent triggers with a single API that brings the key signals into one programmable surface. Using FreightPulse, you can combine lagged-but-actionable port throughput signals, live over-the-road (OTR) rate quotes, national and regional fuel indices, carrier verifications, and natural-disruption alerts to determine — with code — when to advance a shipment to the next step. Whether you are a freight forwarder, a 3PL, or a supply chain SaaS building visibility workflows, your app can shift from “waiting for an email” to “streaming decision signals” in hours, not months.

The goal is not to replace the filing of customs entries or manifest submissions, but to automate the downstream handoffs that follow once clearance is imminent or complete. We will design clearance triggers that account for:

All of that comes from one REST API surface, which means fewer brittle integrations and less vendor management. Let’s build it.

Why FreightPulse

Handoffs are fundamentally orchestration problems. They require data that usually lives in different places and updates on different cadences. FreightPulse consolidates the logistics intelligence most teams need to automate those decisions — with consistent JSON shapes and practical defaults — so you can ship production features faster.

Quick Start

Base URL for all endpoints: 


https://freightpulsehq.com/api/v1

Authentication is sent via the X-API-Key header when needed. Many endpoints allow unauthenticated exploration. All responses follow the envelope: 


{
"success": true | false,
"data": { ... },
"error": "message" // present if success=false
}

First request: national and regional fuel indices. These power surcharge rules that often gate a post-clearance tender release. 


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

Sample response: 


{
"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 can wire to clearance triggers:

Core Endpoints for Clearance-Driven Handoffs

1) Port Congestion: 7-day average vs 90-day baseline

Why it matters: Even when customs clears the entry, cargo cannot roll inland if the terminal is backed up. FreightPulse provides a lagged congestion proxy using IMF PortWatch AIS-derived portcalls: a 7-day average relative to a 90-day baseline. The data has a ~6–7 day lag and is ideal for proactive planning (e.g., schedule drayage a day later or request extended free time) — it is not a live vessel wait-time feed. Use this to conditionally schedule drayage pickups and inland pickups upon clearance.

Endpoint: 


GET /port-congestion

Key parameters:

Example request: 


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

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

How to use:

2) Disruption Alerts: Cyclones, earthquakes, severe weather near a port

Why it matters: Natural hazards are decisive for ground operations the moment a container is released. Before you dispatch drayage or final-mile, check for storms, severe weather, or seismic events near the relevant port. FreightPulse aggregates alerts from GDACS, USGS, and NOAA/NWS and lets you filter by port radius. Use this as a required “green-light” check on your clearance trigger workflow.

Endpoint: 


GET /disruptions

Key parameters:

Example request: 


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

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:

3) Live US FTL Freight Quotes: Inland legs ready to go when clearance hits

Why it matters: As soon as a container clears, a well-timed inland tender can beat other shippers to scarce capacity — especially during peak season. FreightPulse proxies live US full-truckload quotes (via Warp) and unifies the data with the rest of your logistics signals so you can immediately propose a rate and ETA to your consignee.

Endpoint: 


GET /freight-rates

Key parameters (trucking mode):

Example request: 


curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=90802&destination_zip=85001&pickup_date=2026-08-24&qty=1&total_weight_lb=38000"

Sample response: 


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

How to use:

4) Carrier Verification: FMCSA trucking and FMC ocean directories

Why it matters: A clearance workflow often culminates in dispatching a carrier. Before you release a load, verify the carrier’s authority, name, and safety rating. FreightPulse normalizes FMCSA (trucking) and FMC (ocean NVOCC/OTI) lookups under one endpoint, so compliance checks are cheap to add and easy to automate.

Endpoint: 


GET /carriers

Key parameters:

Example request (trucking by DOT number): 


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

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:

5) Fuel Prices and Historical Series: Surcharge logic and trend gating

Why it matters: Your clearance-triggered quotes must respect surcharge policy, and many shippers also gate rate locks on recent fuel trends. FreightPulse offers both current indices and historical series in consistent shapes, making it trivial to codify your rules.

Endpoints:

Example historical request: 


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

Response: 


{
"success": true,
"data": {
"metric": "fuel_price_diesel_national",
"period": "90d",
"series": [
{ "date": "2026-06-01", "value": 3.73 },
{ "date": "2026-06-08", "value": 3.76 },
{ "date": "2026-06-15", "value": 3.79 },
{ "date": "2026-06-22", "value": 3.81 },
{ "date": "2026-06-29", "value": 3.83 }
]
}
}

How to use:

6) Historical Port Congestion Series: Trend visualization for ETA buffers

Why it matters: Trends help operators calibrate buffer days between clearance and pickup. Use the historical series to power dashboards and automated ETA deltas for specific ports.

Endpoint: 


GET /historical?metric=port_congestion:<portid>

Example request (Los Angeles-Long Beach): 


curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/historical?metric=port_congestion:USLAX&period=1y"

Sample response: 


{
"success": true,
"data": {
"metric": "port_congestion:USLAX",
"period": "1y",
"series": [
{ "date": "2025-09-01", "value": 0.92 },
{ "date": "2025-09-08", "value": 0.88 },
{ "date": "2025-09-15", "value": 0.85 }
]
}
}

How to use:

Designing Clearance Triggers that Actually Work

A practical clearance trigger is not a single condition but a compact decision tree that considers clearance status, port throughput, weather risk, carrier compliance, inland rate availability, and surcharge policy. Below is a canonical sequencing pattern:

  1. When an entry status changes to “cleared” in your TMS, fetch port congestion for the destination port to establish a throughput baseline. If the ratio_vs_baseline < 0.7 and labeled “high” congestion, insert a 24–48 hour buffer before dray appointment creation.
  2. Query disruptions by port. If severity is moderate or high for cyclones or severe_weather overlapping your next 48 hours, block auto-dispatch and request operator review.
  3. Request live FTL quotes from the port ZIP to the consignee ZIP for the earliest feasible pickup date. Validate price against policy and current fuel indices, checking your surcharge matrix with national or PADD-region diesel.
  4. Verify the chosen carrier’s DOT number and safety rating before finalizing the tender. If status != active or rating violates your rule, cycle to the next option.
  5. Record every decision with timestamps and raw JSON responses for audit and explainability. If anything fails, backoff and retry with exponential delays, and log soft-fail states to your observability tooling.

The result is a reliable, explainable, and fast handoff orchestration that turns clearance into predictable inland movements.

End-to-End Examples in Code

cURL workflow: from congestion and disruption checks to a rate quote 


# 1) Check port congestion for Los Angeles-Long Beach (USLAX)
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

# 2) Check high-severity disruptions near the same port
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"

# 3) Get an inland FTL quote from Long Beach (90802) to Phoenix (85001)
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=90802&destination_zip=85001&pickup_date=2026-08-24&qty=1&total_weight_lb=38000"

# 4) Fetch current fuel indices for surcharge validation
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/fuel-prices"

Python: clearance trigger decision function 


import os
import time
import requests

BASE = "https://freightpulsehq.com/api/v1"
HEADERS = {"X-API-Key": os.getenv("FREIGHTPULSE_API_KEY", "")}

def get_json(path, params=None, retries=3, backoff=0.5):
for attempt in range(retries):
resp = requests.get(f"{BASE}{path}", headers=HEADERS, params=params, timeout=15)
data = resp.json()
if data.get("success"):
return data["data"]
# Soft error: backoff and retry
time.sleep(backoff * (2 ** attempt))
raise RuntimeError(f"Failed to get {path}: {data.get('error')}")

def should_release_inland_tender(port_locode, origin_zip, dest_zip, pickup_date):
pc = get_json("/port-congestion", {"port": port_locode})
disruptions = get_json("/disruptions", {"port": port_locode, "severity": "high"})

# Basic congestion rule
ratio = None
if pc.get("results"):
ratio = pc["results"][0]["metrics"]["ratio_vs_baseline"]
if ratio is not None and ratio < 0.7:
return {"release": False, "reason": "High congestion, add buffer", "ratio": ratio}

# Disruption rule
if disruptions.get("results"):
return {"release": False, "reason": "Severe disruption near port", "events": disruptions["results"]}

# Live rate
rate = get_json("/freight-rates", {
"mode": "trucking",
"origin_zip": origin_zip,
"destination_zip": dest_zip,
"pickup_date": pickup_date
})

# Fuel index for surcharge check
fuel = get_json("/fuel-prices")
diesel = fuel["data"]["diesel"]["national_average"]

return {
"release": True,
"reason": "Conditions normal",
"congestion_ratio": ratio,
"rate": rate,
"diesel": diesel
}

# Example call:
# result = should_release_inland_tender("USLAX", "90802", "85001", "2026-08-24")
# print(result)

JavaScript/Node: carrier verification before dispatch 


import fetch from "node-fetch";

const BASE = "https://freightpulsehq.com/api/v1";
const HEADERS = { "X-API-Key": process.env.FREIGHTPULSE_API_KEY || "" };

async function fpGet(path, params) {
const url = new URL(BASE + path);
if (params) Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
const res = await fetch(url.toString(), { headers: HEADERS });
const body = await res.json();
if (body.success) return body.data;
throw new Error(body.error || "FreightPulse error");
}

export async function verifyCarrier(dotOrName) {
const data = await fpGet("/carriers", { q: String(dotOrName), type: "trucking" });
const match = (data.results || [])[0];
if (!match) return { ok: false, reason: "No match" };
const { status, safety_rating } = match;
const ok = status === "active" && ["S", "None"].includes(safety_rating);
return { ok, match };
}

// Usage:
// const check = await verifyCarrier(54283);
// if (!check.ok) throw new Error("Carrier blocked by compliance");

Real-World Use Cases

1) Customs-to-Dray Automation for a Freight Forwarder

When ACE/ABI indicates “released,” the forwarder’s TMS runs a congestion check for the terminal using GET /port-congestion and a disruption sweep with GET /disruptions?port=USLAX. If congestion is moderate and no high-severity events exist, the system requests an FTL quote via GET /freight-rates for the inland leg and calculates a fuel surcharge with GET /fuel-prices. The workflow then verifies the intended dray or linehaul partner with GET /carriers before auto-creating the appointment. Operators only step in when conditions fail rules.

2) SaaS Visibility Platform: Predictive Buffer Days

A visibility app layers GET /historical?metric=port_congestion:USLAX with the latest GET /port-congestion snapshot to compute a dynamic buffer applied at “release” time. The UI shows a rolling 90-day congestion trend and recommends adding 0–2 days to inland pickups; the engine also queries GET /disruptions by port to warn of incoming storms that override the statistical buffer. The result is fewer missed gates and more realistic appointment windows surfaced to consignees.

3) 3PL Rate Desk: Surcharge-Aware, Live Tendering

A 3PL embeds GET /freight-rates in its tender bot to price and propose the inland movement immediately after clearance. Before confirming, the bot calls GET /fuel-prices and GET /historical?metric=fuel_price_diesel_national to enforce a cap-if-rising rule for volatile weeks. Finally, GET /carriers ensures the selected motor carrier meets the compliance bar. The operator receives a compiled decision including raw JSON, keeping the process auditable and fast.

FAQ

How often do FreightPulse fuel prices update?

Fuel price data is sourced from EIA and reflects their official publication cadence. FreightPulse normalizes the latest available figures and includes regional PADD breakdowns plus historical averages, allowing you to apply surcharge rules with consistent fields across updates.

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

Yes. Use GET /carriers with type=ocean to query the FMC directory for NVOCC/OTI entities, and with type=trucking (default) to query FMCSA SAFER records. Return fields are normalized where sensible, and air currently returns available:false.

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

No. Port congestion uses IMF PortWatch AIS-derived portcall activity and is provided as a 7-day average relative to a 90-day baseline with a roughly 6–7 day lag. It’s excellent for trend-aware planning and buffer policies, but it is not a live AIS vessel queue metric.

How should I handle missing parameters on GET /freight-rates?

When required parameters are missing, the endpoint returns HTTP 200 with indicators such as available: false in the data rather than an error. Code your client to detect availability and surface a helpful prompt (e.g., “origin_zip required”) instead of failing the workflow.

What is the response envelope shape and how do I handle errors?

Every endpoint returns { success, data, error }. When success=false, error contains a human-readable message. Handle 4xx/5xx HTTP codes with retries and backoff when appropriate, and use the envelope to log and branch decisions without crashing user flows.

Implementation Guidance, Reliability, and Observability

Building production-grade clearance triggers is less about complex algorithms and more about predictable, explainable decisions that remain stable through network hiccups and upstream variability. The practices below help you maintain resilience as you integrate multiple signals.

Endpoint-by-Endpoint Deep Dive and Field Interpretation

GET /fuel-prices

Purpose: Provide current national and regional diesel/gasoline indices for surcharge rules and pricing transparency. Every customs clearance-triggered tender should check these before price presentation.

Key fields:

Performance tips:

GET /freight-rates

Purpose: Retrieve live truckload quotes that you can present the moment clearance occurs, avoiding delays that cede capacity to faster rivals.

Parameters and impact:

Response fields:

Error handling:

GET /port-congestion

Purpose: Provide an actionable proxy for terminal throughput that lets you algorithmically decide whether to auto-dispatch or delay post-clearance.

Field meanings:

Best practices:

GET /carriers

Purpose: Prevent non-compliant dispatches by verifying authority and safety.

Field meanings:

Tips:

GET /disruptions

Purpose: Avoid preventable bad dispatches by screening for severe weather or hazards near the port or route.

Field meanings:

Tips:

GET /historical

Purpose: Trend analysis for buffer policies and surcharge stability. Two primary families: fuel price series and port congestion series.

Parameters:

How to use:

Error Scenarios and Defensive Patterns

Robust automation anticipates and calmly handles the unexpected. FreightPulse exposes explicit error messages while keeping the envelope shape stable.

Performance Tuning and Operational Excellence

Putting It All Together: A Reference JSON Decision Record

Below is a representative composite record you might store each time your system decides to auto-release or hold an inland tender after customs clearance. It combines inputs from multiple FreightPulse endpoints and your own computed verdict. 


{
"shipment_id": "FF-123456",
"decision_at": "2026-08-20T14:22:10Z",
"port": "USLAX",
"inputs": {
"port_congestion": {
"as_of": "2026-08-14",
"congestion": "moderate",
"ratio_vs_baseline": 0.85
},
"disruptions": {
"high_severity_count": 0,
"events": []
},
"freight_rate": {
"mode": "trucking",
"price_usd": 2895.4,
"transit_days": 2,
"pickup_date": "2026-08-24",
"delivery_date": "2026-08-26"
},
"fuel": {
"diesel_national": 3.847,
"region": "west_coast",
"diesel_region_value": 4.456
},
"carrier_verification": {
"dot_number": 54283,
"status": "active",
"safety_rating": "S"
}
},
"policy_evaluations": {
"congestion_threshold": "ratio >= 0.7: PASS",
"weather_block": "no high-severity within 300km: PASS",
"fuel_surcharge_within_bounds": "PASS",
"carrier_compliance": "PASS"
},
"verdict": {
"release_inland_tender": true,
"notes": "Proceed with pickup on 2026-08-24; congestion moderate but acceptable."
}
}

Developer Checklist for Launch

Conclusion + CTA

Customs clearance should be a springboard, not a bottleneck. When your system can independently verify port conditions, screen for weather, fetch a live inland quote, check the carrier’s credentials, and validate surcharge policy, “released” becomes a reliable signal to move — confidently and quickly. FreightPulse brings those signals together in one API, with consistent fields and practical semantics that match how logistics really runs.

The fastest path from a spreadsheet-and-email workflow to an automated, explainable clearance trigger is to ship code against unified logistics intelligence. You can assemble these workflows in days, not months, and give operators both speed and context without burying them under vendor sprawl.

Start building your clearance-triggered handoffs with FreightPulse. Explore the endpoints, wire the decision tree, and turn every “released” into an orchestrated inland move. Try FreightPulse for free and see how quickly your team can go from idea to production-grade automation.