Post loads to Wanload from your own system

Quick start

1. Create a test key. In Wanload, open Settings → Integrations and create a key in Test mode. It works immediately — no verification needed — and starts with wl_test_. The key is shown once.
2. Post a load. One request, below. Loads posted with a test key are flagged sandbox and stay invisible to real carriers, so you can exercise the whole flow safely.
3. Go live. Swap the test key for a live one. Same URL, same payload. See Going live.

Base URL: https://www.wanload.com/api/v1. All requests and responses are JSON.

Authentication

Every request carries your key in the x-api-key header.

x-api-key: wl_<64 hex chars>        # live
x-api-key: wl_test_<64 hex chars>   # sandbox

We store only a hash of the key, so it cannot be shown again — keep it somewhere safe. Each key belongs to exactly one Wanload account: every load it posts is owned by that account, and it can only read, update or cancel that account's loads. There is no way to post under another account's identity.

Create a load

POST /api/v1/loads

curl -X POST https://www.wanload.com/api/v1/loads \
  -H "x-api-key: wl_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "YOUR-LOAD-1",
    "origin_city": "Dallas",       "origin_state": "TX",
    "destination_city": "Atlanta", "destination_state": "GA",
    "pickup_date": "2026-10-01",
    "equipment_type": "dry_van",
    "rate": 1850
  }'

Returns 201 and the full load record. Store the id — every other endpoint is keyed by it. The load_code is the short human-facing reference your customer will see in Wanload.

{
  "success": true,
  "data": {
    "id": "8f14e45f-ea4e-4c72-a0b1-9a2c3d4e5f60",
    "load_code": "A1B2C3",
    "status": "posted",
    "external_id": "YOUR-LOAD-1",
    "origin_city": "Dallas",
    "origin_state": "TX",
    "rate": "1850.00",
    "is_sandbox": true,
    "created_at": "2026-09-26T14:02:11.402Z"
  }
}

Load fields

Required

Optional

Equipment types

Send the exact lower-case value. Carrier equipment filters match on these, so a display label like "Dry Van" would store a load no carrier filter finds.

Safe retries

If a request times out you cannot tell whether the load was created. Two mechanisms make retrying safe; you can use either or both.

1. external_id (recommended)

Send your own id for the load and simply retry. The first call creates it and returns 201; any repeat returns 200 with the original load and idempotent_replay: true. No second load, no second carrier broadcast, no second load.created webhook.

• Unique per account, with live and sandbox counted separately — reusing a test id in production is safe.
• Cancelling a load frees its id, so delete-and-repost works.
• The body of a replayed request is ignored — you get the load as originally posted. To change a live load, use PATCH.
• external_id is immutable; PATCH cannot repoint it, so the mapping always has exactly one answer.
• Omitting it is allowed, but then retries will create duplicates.

2. Idempotency-Key header

For callers with no stable id of their own. Max 255 characters, honoured for 24 hours.

Idempotency-Key: 8f14e45f-ea4e-4c72-a0b1-9a2c3d4e5f60

List and reconcile

GET /api/v1/loads — your loads, newest first. This is how you look up what became of an external_id, or re-sync after an outage without replaying POSTs.

curl "https://www.wanload.com/api/v1/loads?external_id=YOUR-LOAD-1&include_cancelled=true" \
  -H "x-api-key: wl_test_..."

{
  "success": true,
  "data": {
    "loads": [ { "id": "...", "load_code": "A1B2C3", "status": "posted", "external_id": "YOUR-LOAD-1" } ],
    "pagination": { "total": 1, "limit": 20, "offset": 0, "hasMore": false }
  }
}

An unknown status, a typo'd boolean or an empty external_id returns 400 rather than being silently ignored.

Fetch, update, cancel

Update and cancel only work while the load is still posted. Once a carrier has booked it, Wanload's own lifecycle takes over and the API returns 409 with the current status — an external system must not be able to pull freight out from under a booked carrier.

A load id that is not yours returns 404, never 403, so ids cannot be probed.

Webhooks

Set a webhook_url on your key and we POST lifecycle events to it, so you do not have to poll.

Requests carry these headers:

x-wanload-event: load.booked
x-wanload-signature: t=1758196800,v1=<hex hmac>
x-wanload-delivery: <uuid, stable across retries of this event>
x-wanload-attempt: <1-5>

Verifying the signature

Each key has a signing secret (whsec_…), returned once when the key is created. The signature covers "{timestamp}.{raw_body}".

import hmac, hashlib, time

def verify(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    ts = int(parts["t"])
    if abs(time.time() - ts) > tolerance:          # replay window
        return False
    expected = hmac.new(
        secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    # Any v1= may match: during a rotation we send two.
    return any(
        hmac.compare_digest(v, expected)
        for k, v in (p.split("=", 1) for p in header.split(",") if "=" in p)
        if k == "v1"
    )

• Verify against the raw request body, exactly as received. Parsing the JSON and re-serialising it will not match — key order and spacing are not preserved.
• Use a constant-time comparison, not ==.
• Reject timestamps outside your tolerance in either direction.
• Accept the delivery if any v1= matches — during a rotation we send two.

Retries

A failed delivery is retried up to 5 times: immediately, then after 1 minute, 5 minutes, 30 minutes and 2 hours.

• We retry on a network error, a timeout, 5xx, 408 and 429.
• We do not retry other 4xx — if your endpoint rejects the payload, repeating it will not help.
• Your endpoint must be idempotent. Deduplicate on x-wanload-delivery, which is stable across every attempt of the same event.
• We time out after 10 seconds. Acknowledge with a 2xx first, do the work after.

Rotating the signing secret

Rotate from Settings → Integrations → Rotate webhook secret. For 24 hours afterwards we sign with both the new secret and the one it replaced, so your endpoint keeps verifying whether or not you have redeployed yet. You cannot rotate twice inside that window.

Limits

A retry answered as a replay does not count against the daily limit, so retrying safely costs you nothing. The limit is per account, not per key — minting extra keys does not raise it. If you legitimately need more, contact us rather than working around it.

Errors

Every response is { success: true, data } or { success: false, error }, and carries an x-wanload-request-id header. Quote that id and we can find your exact call.

Going live

Sandbox keys skip every trust check, because sandbox loads never reach a carrier. A live key needs the posting account to be in good standing:

• A payment method on file. Wanload charges the platform fee to the account that owns the load, on delivery.
• ID verification approved, for keys you created yourself.
• For broker accounts, an FMCSA-verified USDOT or MC number. Operating authority is not waived — a card says the fee is collectable, not that the entity may broker freight.
• No unpaid platform-fee balance.

Nothing else changes: same base URL, same payload, same behaviour. Swap the key.

Running a TMS?

If your customers post to Wanload through your platform, we can provision a Wanload account and key per customer, and bill each of them directly — you never touch payments. Email partners@wanload.com and we will issue you a partner provisioning key.