Home → Blog

You’re building a multitenant supply chain SaaS and need a clean way to contract your external data, trace it end-to-end per tenant, and bill accurately for the API work each customer triggers. By the end of this post, you’ll be able to define data contracts for FreightPulse responses, attach lineage and tenant context to every call, and wire usage metering that cleanly separates and invoices tenants without crosstalk.

Introduction

Multitenant logistics platforms constantly ingest third-party data: diesel price benchmarks for fuel surcharges, live truckload quotes, carrier verifications, port congestion signals, and disruption alerts. Without rigorous data contracts and lineage, those feeds morph into brittle glue code, unexplainable totals at billing time, and the occasional tenant data leak across environments.

FreightPulse consolidates core logistics intelligence behind one REST API. That helps, but it doesn’t automatically give you tenant isolation or audit-grade usage tracking. The key is to wrap FreightPulse with explicit data contracts and lineage hooks that turn every response into a typed payload with provenance, versioning, and cost attribution. The result: reliable pricing calculators, clean tenant boundaries, and a bill your finance team and customers can both verify.

Why FreightPulse

FreightPulse combines multiple operations-critical data surfaces behind one API. For multitenant SaaS, that means fewer connector types to govern and a single integration surface to contract and monitor. Concretely:

Quick Start

FreightPulse is a REST API with a single base URL and an authentication header. Unauthenticated requests are allowed in limited quantities for exploration, but production services should send an API key.

First request: read national and regional diesel/gasoline benchmarks from EIA via FreightPulse. This is the backbone for a fuel-surcharge engine and a great example to define your first data contract.

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

Example JSON response (values are illustrative but use the documented fields):

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

What to read and store:

Core Endpoints

This section shows how to build durable data contracts and lineage around three common logistics capabilities while highlighting the key fields that affect tenant billing and isolation.

1) Fuel Benchmarks for Surcharges

Endpoint: GET /fuel-prices

Key params: none

Sample request:

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

Response fields to contract:

Notes for lineage:

2) Live US FTL Freight Quotes

Endpoint: GET /freight-rates

Key params:

Sample request (FTL dry van):

curl -s -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"
}
}

Contract and lineage tips:

3) Port Congestion (Lagged Approximation)

Endpoint: GET /port-congestion

Key params:

Sample request:

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

Important constraints to codify in your contract:

4) Carrier Verification (FMCSA/FMC)

Endpoint: GET /carriers

Key params:

Sample request (trucking by DOT number):

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

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

Contract and lineage:

5) Natural-Disruption Alerts

Endpoint: GET /disruptions

Key params:

Sample request (high-severity near USLAX):

curl -s -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"
}
]
}
}

Contract and lineage:

Designing Data Contracts for Multitenant Ingestion

Data contracts specify the exact fields you ingest per endpoint, their types, and the invariants you expect (units, currency, lags). With FreightPulse, all responses share a standard envelope. Your contract can standardize a few concerns across endpoints and isolate tenant-specific projections.

Recommended envelope contract for ingestion (your internal schema, not an API requirement):

{
"tenant_id": "uuid-or-slug",
"ingest_at": "2026-08-24T10:15:00Z",
"source_service": "freightpulse",
"fp_endpoint": "/fuel-prices",
"fp_request": {
"querystring": "mode=trucking&origin_zip=10001&destination_zip=90210",
"headers": ["X-Request-Id: ..."]
},
"fp_response": {
"success": true,
"data": { ... } // raw FreightPulse data block
},
"contract_version": "fuel_prices.v1",
"schema_fingerprint": "sha256:...",
"result_available": true
}

Key practices:

Implementing Lineage and Tenant Isolation

Lineage must let you answer: which tenant triggered a call, which inputs were used, what raw outputs were returned, and which derived values fed invoices or UIs.

Isolation tips:

Metering and billing:

A Small Client Example with Field-Level Validation

The following snippet fetches fuel prices and validates the currency and unit per your contract. Use the same headers and base URL for other endpoints.

# Python 3.x
import requests
from datetime import datetime

BASE_URL = "https://freightpulsehq.com/api/v1"
API_KEY = "YOUR_API_KEY"

def get_fuel_prices(tenant_id: str):
resp = requests.get(f"{BASE_URL}/fuel-prices", headers={"X-API-Key": API_KEY}, timeout=10)
payload = resp.json()
assert payload.get("success") is True, payload.get("error")

data = payload["data"]
# Contract checks
assert data["currency"] == "USD", "Unexpected currency"
assert data["unit"] == "gallon", "Unexpected unit"
ts = datetime.fromisoformat(data["timestamp"].replace("Z", "+00:00"))

diesel = data["data"]["diesel"]
national = float(diesel["national_average"])
regions = diesel["regions"]

record = {
"tenant_id": tenant_id,
"ingest_at": datetime.utcnow().isoformat() + "Z",
"fp_endpoint": "/fuel-prices",
"contract_version": "fuel_prices.v1",
"result_available": True,
"raw": payload, # keep raw for lineage
"projection": {
"timestamp": data["timestamp"],
"national_diesel_usd_per_gal": national,
"regions": regions
}
}
return record

if __name__ == "__main__":
print(get_fuel_prices("tenant_abc"))

Real-World Use Cases

Practical Integration Details That Save Time

End-to-End Example: Building a Tenant-Isolated Lane Quote Service

Goal: Provide tenants with same-page live FTL quotes and a surcharge overlay, with clean lineage and itemized usage.

  1. Standardize the input. Contract a request DTO with tenant_id, origin_zip, destination_zip, pickup_date, and optional cargo attributes.
  2. Fetch the live quote. Call /freight-rates with trucking mode. Persist raw response + inputs + a hash of the raw JSON. If any required param is missing and you receive "available": false, persist that outcome for billing visibility.
  3. Fetch the fuel baseline. Call /fuel-prices once per day per tenant and cache, then reference the cached baseline within your quote flow to compute tenant-specific surcharge.
  4. Derive and store the final projection. The derived object includes price_usd, transit_days, surcharge_percent, and total_with_surcharge. Attach references to both raw ingestion records by their hashes.
  5. Emit usage metrics. Increment counters: freight_rates.calls, fuel_prices.cache_hits, fuel_prices.calls. Roll up by tenant_id daily.

One-Stop Historical Context

For trendlines and SLA reporting, pull historical time series directly rather than rolling your own aggregates from ad-hoc calls.

Endpoint: GET /historical

Key params:

Sample request:

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

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

Contract notes:

FAQ

How often do FreightPulse fuel prices update?

Fuel prices originate from EIA and reflect weekly benchmarks. The response includes a timestamp and fields like change_week and change_percent. Cache them prudently and display the timestamp in UI and invoices.

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

Yes. Use /carriers with type=ocean to query NVOCC/OTI entries from the FMC directory. Air returns available:false, so scope your UI accordingly.

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

No. Congestion is a lagged approximation: a 7-day average of portcalls versus a 90-day baseline, typically delayed by about 6–7 days. Use ratio_vs_baseline and the congestion label for planning, not minute-by-minute operational control.

Can I explore the API without an API key?

Yes, unauthenticated requests are allowed for limited exploration per IP. For production and consistent throughput, send the X-API-Key header.

What error shape should my client expect?

All responses share {"success": true|false, "data": {...}, "error": "..."} and standard HTTP codes such as 401, 403, 422, and 429. Log both the HTTP status and the error field to speed up troubleshooting.

Conclusion + CTA

Data contracts and lineage are the difference between a multitenant product that scales and one that’s impossible to reconcile at invoice time. By contracting FreightPulse payloads, keeping raw responses immutable, and attaching tenant context and request fingerprints, you can ship features like surcharge calculators, live quotes, and risk dashboards while maintaining strict tenant isolation and transparent billing.

FreightPulse gives your team one API surface for fuel benchmarks, live freight quotes, port congestion signals, carrier verifications, and disruption alerts. That consolidation simplifies contracts, reduces integration risk, and accelerates time to production.

FreightPulse brings these datasets together behind one REST API so you can focus on product. Try FreightPulse for free and start wiring your data contracts and lineage today.