Connect your TMS

OpenAPI specification

The complete machine-readable contract is published at /developers/openapi.json. You can inspect or download it to generate API clients or automated tests:

Download openapi.json

Build it with Claude Code or Codex

To integrate your TMS quickly using Claude Code or Codex, follow these steps:

1. Create an API key in Settings under the TMS connection section.
2. Store the key as an environment variable in your terminal session (never put API keys in code or commits):

   export HLB_API_KEY="hlb_your_api_key_here"

3. Run the tool with the integration prompt:

   With Claude Code:

   claude "Read https://honestloadboard.com/developers/openapi.json and write a script that posts loads from our TMS to Honest Load Board, retries safely with externalId, and verifies the HLB-Signature header on webhooks."

   With Codex:

   codex "Read https://honestloadboard.com/developers/openapi.json and write a script that posts loads from our TMS to Honest Load Board, retries safely with externalId, and verifies the HLB-Signature header on webhooks."

API keys

You can create up to 5 API keys from your broker account. In Settings, go to the TMS connection section and click Create API key. Copy the key when it appears; it is shown only once and stored on the server as a keyed hash.

Pass your key in the Authorization header on every call:

Authorization: Bearer hlb_your_api_key_here

Requests are limited to 60 calls per minute per key. Responses and requests use JSON.

Endpoints

1. Post a load

POST /api/honest-load-board/v1/loads

Posts a load to the board. If you supply an externalId (your own load reference number), posting the same load again returns the existing load with status 200 without creating a duplicate or taking posting credit.

curl -X POST https://honestloadboard.com/api/honest-load-board/v1/loads \
  -H "Authorization: Bearer hlb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": "2026-10-31",
    "externalId": "LOAD-2026-9041",
    "pickup": {
      "street": "4100 W 42nd Pl",
      "city": "Chicago",
      "state": "IL",
      "zip": "60632",
      "start": "2026-11-05T14:00:00Z",
      "end": "2026-11-05T18:00:00Z"
    },
    "delivery": {
      "street": "1200 S 5th Ave",
      "city": "St. Charles",
      "state": "IL",
      "zip": "60174",
      "start": "2026-11-06T08:00:00Z",
      "end": "2026-11-06T12:00:00Z"
    },
    "equipment": "dry_van",
    "loadType": "live_both",
    "weightLbs": 38000,
    "startPrice": 850,
    "topPrice": 1190,
    "risePerStep": 50,
    "stepMinutes": 30,
    "fuelSurchargeIncluded": true,
    "rush": false,
    "minAuthorityDays": 90,
    "lumper": { "needed": false }
  }'

2. List your loads

GET /api/honest-load-board/v1/loads

Returns all loads posted by your broker company. Once booked, each load includes the carrier legal name, MC number, booked price and booking time.

curl https://honestloadboard.com/api/honest-load-board/v1/loads \
  -H "Authorization: Bearer hlb_your_key"

3. Get a load

GET /api/honest-load-board/v1/loads/:id

Returns a single load by ID.

curl https://honestloadboard.com/api/honest-load-board/v1/loads/48a31828-59df-4cb7-b249-f41cb8380da1 \
  -H "Authorization: Bearer hlb_your_key"

4. Cancel a load

POST /api/honest-load-board/v1/loads/:id/cancel

Cancels an open load before it is booked or before pickup cutoff.

curl -X POST https://honestloadboard.com/api/honest-load-board/v1/loads/48a31828-59df-4cb7-b249-f41cb8380da1/cancel \
  -H "Authorization: Bearer hlb_your_key"

Field reference

• terms: "2026-10-31" or "2026-11-01" (required agreement).
• externalId: optional string up to 120 characters for your internal reference.
• pickup: street, city, 2-letter state, 5-digit ZIP, start (ISO timestamp in future, more than 1 hour away), end (ISO timestamp >= start).
• delivery: street, city, 2-letter state, 5-digit ZIP, start (ISO timestamp > pickup start), end (ISO timestamp >= delivery start).
• equipment: dry_van, reefer, flatbed, step_deck.
• loadType: live_both, drop_hook, empty_live_drop, load_out, live_load, live_unload.
• weightLbs: integer from 1 to 120,000.
• startPrice, topPrice, risePerStep: dollar amounts greater than 0. Top price must be higher than start price and at most 40% above start price.
• stepMinutes: price interval in whole minutes (1 or more). The price must reach top price before pickup minus 1 hour.
• fuelSurchargeIncluded: must be true. All prices on Honest Load Board are all-in.
• rush: boolean (true or false).
• minAuthorityDays: 90 or 0.
• lumper: { "needed": false } or { "needed": true, "paidBy": "broker" | "reimbursed" }.
• Reefer fields: when equipment is reefer, temperatureF (−40 to 90) and minus10Capable (boolean) are required.
• Flatbed / Step deck fields: when equipment is flatbed or step_deck, tarpDropFt (4, 6 or 8) and chainsRequired (boolean) are required.
• Load out fields: when loadType is load_out, returnBy (ISO timestamp after delivery end) is required.

Webhooks

Save your HTTPS webhook URL in Settings under TMS connection. A 32-byte signing secret is shown once. Webhook events are delivered with a 10-second timeout and retried up to 5 times.

Event types

• load.booked: Sent when a vetted carrier finishes check-in and photo review is confirmed. The load payload includes carrier legal name, MC number, booked price and booking time.
• load.cancelled: Sent when you cancel a load.
• load.closed: Sent when the 1-hour pickup window arrives without a booking and the load closes.
• load.test: Sent when you click Send test event.

Payload structure

{
  "id": "76ecb8b3-da65-4f36-9e9f-68e54728f321",
  "type": "load.booked",
  "createdAt": "2026-11-05T15:30:00.000Z",
  "load": { ... }
}

Verifying signatures

Each delivery includes the HLB-Signature header with timestamp t and HMAC-SHA256 hash v1 computed over t + "." + raw_body using your secret:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyWebhook(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(',').map(s => s.trim().split('=')));
  const t = parts.t;
  const expected = parts.v1;
  const hash = createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
  return timingSafeEqual(Buffer.from(hash), Buffer.from(expected));
}