FreightConnect

Integrations / Api Overview

API Overview

FreightConnect provides a REST API for programmatic access to loads, carriers, rates, and settlements. Integrate your TMS, accounting software, or custom tools.

Authentication

All API requests require an API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.freightconnect.ai/v1/loads

Generate a key in Settings → Integrations → API Keys. Keys never expire, but you should rotate them every 90 days for security. Revoke old keys when no longer needed.

Rate Limits

  • Free/Solo plans: 100 requests/minute
  • Brokerage plans: 1,000 requests/minute
  • Enterprise plans: custom limits

If you exceed the limit, you get a 429 (Too Many Requests) response. Back off and retry after 60 seconds.

Base URL

https://api.freightconnect.ai/v1

All endpoints are prefixed with /v1. We maintain backward compatibility; v2 will be announced 12 months in advance.

Endpoints

Loads

POST /loads — Create a new load

{
  "pickup_address": "123 Main St, Los Angeles, CA 90001",
  "delivery_address": "456 Park Ave, New York, NY 10001",
  "pickup_date": "2026-04-15T08:00:00Z",
  "weight_lbs": 25000,
  "equipment_type": "dry_van",
  "commodity": "electronics",
  "freight_class": 85,
  "rate": 2.15,
  "shipper_name": "XYZ Electronics",
  "shipper_email": "ops@xyz.com",
  "shipper_phone": "+1-555-0123"
}

Response: 201 Created

{
  "id": "load_abc123",
  "status": "draft",
  "created_at": "2026-04-13T14:30:00Z"
}

GET /loads — List all loads with optional filters

GET /loads?status=active&carrier_id=carr_xyz&limit=20&offset=0

Response: 200 OK

{
  "loads": [...],
  "total": 1234,
  "limit": 20,
  "offset": 0
}

GET /loads/{id} — Get a specific load

Response: 200 OK with full load object (all details, carrier quote, tracking, etc.)

PATCH /loads/{id} — Update a load (only before posting)

{
  "rate": 2.25,
  "special_instructions": "Liftgate required"
}

POST /loads/{id}/post — Post a load to the carrier network

Response: 202 Accepted — querying carriers asynchronously; check status via GET /loads/{id}

DELETE /loads/{id} — Cancel a load (only if pending quotes, no accepted carrier yet)

Carriers

GET /carriers — List all carriers in your network with filters

GET /carriers?min_fsc_score=70&insurance_verified=true

GET /carriers/{id} — Get carrier details (FSC score, FMCSA rating, recent loads, performance)

POST /carriers/{id}/rate-agreement — Set a standing rate with a carrier

{
  "rate": 1.95,
  "rate_type": "per_mile",
  "territory": "midwest",
  "effective_from": "2026-04-15",
  "effective_to": "2026-06-30"
}

POST /carriers/{id}/blacklist — Remove a carrier from your network (they can no longer quote your loads)

Shipments & Tracking

GET /shipments/{load_id}/tracking — Get real-time tracking data

Response: 200 OK

{
  "status": "in_transit",
  "current_location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "address": "New York, NY",
    "timestamp": "2026-04-13T14:25:00Z"
  },
  "estimated_delivery": "2026-04-15T16:00:00Z",
  "events": [...]
}

POST /shipments/{load_id}/update — Manually update shipment status (for carriers without ELD)

{
  "status": "picked_up",
  "notes": "Picked up at 08:30am, running 15min late",
  "timestamp": "2026-04-15T08:30:00Z"
}

GET /shipments/{load_id}/pod — Get proof of delivery

Response: 200 OK

{
  "status": "delivered",
  "pod": {
    "photo_url": "https://...",
    "signature_url": "https://...",
    "timestamp": "2026-04-15T17:45:00Z",
    "notes": "Delivered to dock, signed by John Smith"
  }
}

Settlements

GET /settlements — List all settlement records

GET /settlements?status=pending&min_amount=500

GET /settlements/{load_id} — Get settlement details for a specific load

{
  "load_id": "load_abc123",
  "shipper_charge": 5397.50,
  "carrier_cost": 4650.00,
  "margin": 747.50,
  "margin_percent": 13.8,
  "invoice_date": "2026-04-15T17:45:00Z",
  "payment_due_date": "2026-04-29",
  "payment_received_date": null,
  "status": "pending"
}

POST /settlements/{load_id}/dispute — File a settlement dispute

GET /settlements/{load_id}/dispute — Check dispute status

Webhooks

POST /webhooks — Register a webhook URL to receive events

{
  "url": "https://your-app.com/freightconnect-webhook",
  "events": ["load.posted", "quote.accepted", "shipment.delivered"]
}

GET /webhooks — List registered webhooks

DELETE /webhooks/{webhook_id} — Remove a webhook

Common Scenarios

Create and post a load from your TMS

# 1. Create load
curl -X POST https://api.freightconnect.ai/v1/loads \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"pickup_address":"...", ...}'

# 2. Post to network
curl -X POST https://api.freightconnect.ai/v1/loads/load_abc123/post \
  -H "Authorization: Bearer YOUR_KEY"

# 3. Poll for quotes (or use webhook)
curl -X GET https://api.freightconnect.ai/v1/loads/load_abc123 \
  -H "Authorization: Bearer YOUR_KEY"

# 4. Accept best quote when ready
curl -X POST https://api.freightconnect.ai/v1/loads/load_abc123/accept \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"quote_id":"quote_xyz"}'

Get real-time tracking

curl -X GET https://api.freightconnect.ai/v1/shipments/load_abc123/tracking \
  -H "Authorization: Bearer YOUR_KEY"

Auto-create accounting journal entries from settlements

# Get settled loads from the last day
curl -X GET "https://api.freightconnect.ai/v1/settlements?status=paid&created_after=2026-04-12T00:00:00Z" \
  -H "Authorization: Bearer YOUR_KEY"

# For each settlement, post to your accounting system
# POST https://your-quickbooks.com/journal-entries \
#   -d '{"account":"A/P Carriers","amount":4650,"load_id":"load_abc123"}'

Error Handling

All errors return JSON:

{
  "error": "invalid_load",
  "message": "Load with ID load_abc123 not found"
}

Common status codes:

  • 200 — success
  • 201 — created
  • 202 — accepted (async operation started)
  • 400 — bad request (validation error)
  • 401 — unauthorized (bad API key)
  • 403 — forbidden (insufficient permissions)
  • 404 — not found
  • 429 — too many requests (rate limited)
  • 500 — server error (rare; contact support)

SDKs & Libraries

Official SDKs available for:

  • Python — pip install freightconnect
  • Node.js — npm install freightconnect
  • Go — go get github.com/boldera-labs/freightconnect-go

Community SDKs (maintained by users):

  • C#, Java, Ruby — see GitHub

Webhooks (Advanced)

Instead of polling for updates, register webhooks to receive events:

Events:

  • load.posted — load was posted to carrier network
  • quote.received — carrier submitted a quote
  • quote.accepted — you accepted a quote
  • shipment.picked_up — pickup confirmed
  • shipment.delivered — delivery confirmed
  • settlement.paid — carrier payment received

Each webhook includes the full load/shipment/settlement object.

Signature verification: Every webhook includes an X-FreightConnect-Signature header. Verify it:

import hmac
import hashlib

signature = request.headers['X-FreightConnect-Signature']
body = request.body
expected = hmac.new(
  WEBHOOK_SECRET.encode(),
  body,
  hashlib.sha256
).hexdigest()

assert signature == expected  # request is authentic

Support

  • Documentation: https://freightconnect.ai/docs/api/openapi
  • Support: matt@freightconnect.ai
  • Status: https://status.freightconnect.ai

What's Next

Last updated: April 2026