HeavyHaul GPT - API Documentation

Introduction

The HeavyHaul GPT API lets you submit heavy-haul transport orders from any TMS platform. Send structured order data or upload documents (rate confirmations, registrations, IFTA, COI) and our AI extracts all required fields automatically.

Base URL

https://heavyhaulgbt.com/api/v1

All requests must be made over HTTPS. HTTP requests will be rejected.

TMS Integration

Before making API calls, complete TMS integration setup and get a secret API key.

How to Set Up Integration

Go to the TMS Integration Page.
Fill in: Platform Name, Platform URL, POC Name, and Work Email.
Click "Generate Key". A secret API key will be emailed to you.
Save it in your environment:
HEAVYHAUL_API_KEY=<your-key>

Keep your API key secret. Do not expose it in client-side code, public repos, or share it publicly. If compromised, contact support immediately.

Authentication

Every request must include your secret key in the X-API-KEY HTTP header.

Header Format

X-API-KEY: your_api_key_here

Error Responses

Status	Meaning
401	API key is missing from the request header.
401	API key is invalid.
503	Order intake is temporarily unavailable. Please try again later.
429	Rate limit exceeded. Max 20 requests per 60 seconds per key.

Create Order

Submit an order with carrier, truck, trailer, routing, commodity, and contact details. Optionally attach document URLs or upload files for AI-powered data extraction.

POST /api/v1/order

Parameter	Value
`Content-Type`	`application/json` or `multipart/form-data` (when uploading files)
`X-API-KEY`	Your secret API key required
Rate Limit	20 requests per 60 seconds per API key
File Formats	PDF, JPG, PNG accepted

Request Body

contact required

Requests without driver and client email are rejected with 400.

Field	Type	Required	Description
`driver_first_name`	string	yes	Driver's first name
`driver_last_name`	string	yes	Driver's last name
`driver_email`	string	yes	Driver's email address
`driver_phone`	string	no	Driver's phone number
`client_first_name`	string	yes	Client's first name
`client_last_name`	string	yes	Client's last name
`client_email`	string	yes	Client's email address
`client_phone`	string	no	Client's phone number

carrier partially required

Motor carrier details. The API requires carrier.mc_number and carrier.dot_number. If the training trigger values are sent, the carrier block is overwritten internally with the training profile.

Field	Type	Required	Description
`name`	string	no	Carrier company name
`mc_number`	string	yes	MC number
`dot_number`	string	yes	DOT number
`tax_id`	string	no	Tax ID / EIN
`ifta_license`	string	no	IFTA license number
`email`	string	no	Carrier email
`phone`	string	no	Carrier phone
`address`	string	no	Street address
`city`	string	no	City
`state`	string	no	State abbreviation (e.g., IL)
`zip`	string	no	ZIP code
`insurance_expiration_date`	string	no	COI expiration date (YYYY-MM-DD)

truck partially required

Power unit details. The API requires truck.vin. Other fields auto-extracted from truck registration document if provided.

Field	Type	Required	Description
`unit_number`	string	no	Unit ID number
`year`	string	no	Year of manufacture
`make`	string	no	Make (e.g., FREIGHTLINER)
`model`	string	no	Model
`license_plate`	string	no	License plate number
`registration_state`	string	no	Registration state
`vin`	string	yes	Vehicle identification number
`axle_count`	string	no	Number of axles
`pusher`	string	no	Pusher axle information
`empty_weight_lbs`	string	no	Empty weight in lbs

trailer partially required

Trailer details. The API requires trailer.vin. Other fields auto-extracted from trailer registration if provided.

route required

The route schema supports multiple stops. Use pickups and deliveries arrays. At least one pickup and one delivery with address and date are required.

Field	Type	Required	Description
`pickups[].address`	string	yes	Full pickup address
`pickups[].date`	string	yes	Pickup date
`pickups[].state`	string	no	Auto-extracted from address if blank
`deliveries[].address`	string	yes	Full delivery address
`deliveries[].date`	string	yes	Delivery date
`deliveries[].state`	string	no	Auto-extracted from address if blank

commodity required

Commodity dimensions use a nested {feet, inch} format. All three dimensions and weight are required.

Field	Type	Required	Description
`length`	object	yes	`{"feet": "", "inch": ""}` — commodity length
`width`	object	yes	`{"feet": "", "inch": ""}` — commodity width
`height`	object	yes	`{"feet": "", "inch": ""}` — commodity height
`weight`	string	yes	Commodity weight in lbs
`customer_load_number`	string	no	Your internal load/order number
`description`	string	no	Commodity description
`pieces`	string	no	Number of pieces
`bill_of_lading_number`	string	no	Bill of lading number

route_states / route_dates auto-populated

These arrays are automatically populated by the system. route_states contains the pickup and delivery state codes extracted from addresses. route_dates contains the UTC timestamp when the order was received. You do not need to send these.

documents partially required

Provide document URLs as an array with one object. The API requires documents[0].rate_confirmation. Our AI will download and extract relevant data from each document type.

Field	Required	Description
`rate_confirmation`	yes	Rate Confirmation - extracts carrier, commodity, and route details
`truck_registration`	no	Truck Registration - extracts VIN, make, model, plate, weight, axles
`trailer_registration`	no	Trailer Registration - extracts VIN, make, model, axles
`ifta_certificate`	no	IFTA Certificate - extracts IFTA license number
`insurance_certificate`	no	Certificate of Insurance - extracts liability policy expiration date

Documents

You can provide documents in two ways:

Option A - URL Links

Include public file URLs in the documents array of your JSON payload (first object is used). Our system will download and process them automatically.

Option B - File Upload

Upload files directly using multipart/form-data. Send your JSON data in a form field named data, and attach files with field names: rate_confirmation, truck_registration, trailer_registration, ifta_certificate, insurance_certificate.

Accepted file formats: PDF, JPG, PNG. Maximum recommended file size: 10 MB per document.

Response

A successful response returns only the order creation confirmation payload.

Success Response (202 Accepted)

{
  "status": "success",
  "order_id": "SP-123456",
  "message": "Order received. Final confirmation will be sent after downstream creation completes.",
  "order_status": "received"
}

The full consolidated payload is saved internally in MongoDB. The API response intentionally returns only a minimal success object. A confirmation email is sent after downstream processing completes.

Status Codes

202

Accepted - Order created. Returns status, order_id, and message.

400

Bad Request - Missing required fields such as contact details, carrier.mc_number, carrier.dot_number, or documents.rate_confirmation.

401

Unauthorized - API key is missing or invalid.

503

Unavailable - Order intake is temporarily unavailable for this TMS account. Try again later.

429

Rate Limited - More than 20 requests were sent within 60 seconds for the same API key.

500

Server Error - An unexpected error occurred. Contact support if this persists.

AI Prompt Helper

Copy this prompt and paste it into ChatGPT, Claude, or Cursor to generate a complete integration in seconds.

You are an expert backend engineer. Build a complete integration that sends TMS orders to HeavyHaul. Requirements: - Endpoint: POST https://heavyhaulgbt.com/api/v1/order - Auth: header X-API-KEY from env HEAVYHAUL_API_KEY - Rate limit: 20 requests / 60 seconds per key (retry on 429 with exponential backoff) - Mandatory contact fields: driver_first_name, driver_last_name, driver_email, client_first_name, client_last_name, client_email driver_phone and client_phone are optional - Mandatory: carrier.mc_number, carrier.dot_number, documents.rate_confirmation - Route schema: route.pickups[] route.deliveries[] - Success response: { "status": "success", "order_id": "SP-123456", "message": "Order successfully created." } - Training trigger: carrier.mc_number = 1130384t carrier.dot_number = 3462028 - Files: accept file URLs OR multipart uploads. If URL provided, download (stream), attach as multipart. Accept PDF, JPG, PNG. Clean temp files. Deliverables (produce code + docs): 1. Small SDK/library for Node (TypeScript) and Python: - validation, mapping, file handling, retries. 2. A sample adapter app (Express + FastAPI) with an /integrate endpoint. 3. CLI scripts (node & python) to send a sample JSON. 4. Unit tests (Jest / pytest) and a minimal CI workflow. 5. README with exact run steps, env setup, and one curl example. 6. One sample JSON payload (minimal valid) and one multipart example.

Manual Integration

Follow these two steps to integrate with HeavyHaul manually.

Step A - Prepare & Validate

Set up TMS integration and set HEAVYHAUL_API_KEY in your server environment.
Map your TMS data to our schema. Required: contact.driver_first_name, contact.driver_last_name, contact.driver_email, contact.client_first_name, contact.client_last_name, contact.client_email, carrier.mc_number, carrier.dot_number, and documents.rate_confirmation. If any are missing, return a validation error before calling the API.
Use the current route format: route.pickups and route.deliveries, both as arrays of stop objects.
Other sections remain optional: carrier.name, truck, trailer, commodity, axles, and the non-ratecon document fields.
Files: provide public file URLs in the documents object, or upload directly via multipart/form-data. Accepted formats: PDF, JPG, PNG.

Step B - Send & Handle

Send a POST request to https://heavyhaulgbt.com/api/v1/order.
Include header X-API-KEY: your_api_key.
Use application/json when sending data only. Use multipart/form-data when uploading files.
Expect a minimal success response with order_id instead of the full payload.
Handle rate limiting: on 429 responses, implement retry with exponential backoff.

Full Payload Schema

Copy the empty JSON template below as a starting point for your integration.

contact

required▶

"contact": {
  "driver_first_name": "",
  "driver_last_name": "",
  "driver_email": "",
  "driver_phone": "",
  "client_first_name": "",
  "client_last_name": "",
  "client_email": "",
  "client_phone": ""
}

carrier

optional▶

"carrier": {
    "name": "", "mc_number": "", "dot_number": "", "tax_id": "",
    "ifta_license": "", "email": "", "phone": "", "address": "",
    "city": "", "state": "", "zip": "", "insurance_expiration_date": ""
}

truck

optional▶

"truck": {
    "unit_number": "", "year": "", "make": "", "model": "",
    "license_plate": "", "registration_state": "", "vin": "",
                    "axle_count": "", "pusher": "", "empty_weight_lbs": ""
}

trailer

optional▶

"trailer": {
    "unit_number": "", "type": "", "year": "", "make": "",
    "model": "", "vin": "", "axle_count": "", "tire_count": "",
    "kingpin_to_rear_axle_distance": "", "has_drop_axle": false
}

route / commodity / axles / documents

optional▶

"route": {
    "pickups": [
        { "address": "", "city": "", "state": "", "zip": "", "date": "" }
    ],
    "deliveries": [
        { "address": "", "city": "", "state": "", "zip": "", "date": "" }
    ]
},
"route_states": [],
"route_dates": [],
"commodity": {
    "customer_load_number": "", "bill_of_lading_number": "", "description": "",
    "pieces": "", "weight": "",
    "length": { "feet": "", "inch": "" },
    "width": { "feet": "", "inch": "" },
    "height": { "feet": "", "inch": "" },
    "equipment_make": "", "equipment_model": ""
},
"axles": [
    { "tire_count": "", "weight_lbs": "" }
],
"documents": [
    {
        "rate_confirmation": "", "truck_registration": "", "trailer_registration": "",
        "ifta_certificate": "", "insurance_certificate": ""
    }
]

Complete your TMS integration in under 10 minutes

Introduction

TMS Integration

Authentication

Error Responses

Create Order

Request Body

contact required

carrier partially required

truck partially required

trailer partially required

route required

commodity required

route_states / route_dates auto-populated

documents partially required

Documents

Response

Status Codes

AI Prompt Helper

Manual Integration

Step A - Prepare & Validate

Step B - Send & Handle

Full Payload Schema