Cover a load

Post the load

Turn what the person told you into fields. Every field is on the POST /v1/loads page.

curl -X POST https://agent.lanesurf.com/v1/loads \
  -H "Authorization: Bearer $LANESURF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "equipment_type": "Dry Van",
    "weight_lbs": 40000,
    "rate_max": 1800,
    "reference_number": "PO-4471",
    "origins": [{"city": "Dallas", "state": "TX", "pickup_ready_date": "2026-10-23"}],
    "destinations": [{"city": "Atlanta", "state": "GA", "delivery_ready_date": "2026-10-24"}]
  }'

Answer what's missing

To start covering a load, Lanesurf needs: equipment, the first pickup’s city, state and date, and the last delivery’s city, state and date. If any is missing you get 422:

{ "code": "missing_fields", "missing": ["destinations[0].delivery_ready_date"] }

Ask the person for those only, add them, and send the whole load again.reference_number is optional: your own load number (your TMS or customer reference). It shows on the load and in the Lanesurf dashboard, so loads match between your systems.Values are checked before anything is posted. A bad one answers 400 invalid_request saying which field and why, and nothing is created:

Stops: at most 20. A state is a US state, Canadian province or Mexican state, as its code (TX) or its name (Texas); Lanesurf stores the code.
Dates: the first pickup can’t have passed, and no delivery can be before it.
Numbers: rates from $1 to $500,000 (rate_min no more than rate_max), weight from 1 to 200,000 lbs, pallets 0 to 100, temperature -60 to 120 °F. Commas may group thousands ("$1,950").
Text: plain text within the lengths in the API reference, no HTML tags. Currency is USD, CAD or MXN.
Only the documented fields. Any other field is refused, not ignored. Put anything else carriers must know (a hazmat class, tarps, appointment notes) in explicit_special_instructions.

If Lanesurf can’t process the load (bad stop cities, states, zip codes or dates), you get 400 load_rejected. Don’t send it again unchanged: check the stops and dates with the person, then send it with a new Idempotency-Key.

Lanesurf starts covering it

{
  "status": "sourcing",
  "load_id": "3f2a…",
  "tms_id": "api-7c1e…",
  "post_with": { "email": "jane@loads.example.com", "phone": "+14155550100" },
  "assumed": { "commodity": "General freight" }
}

When the answer has post_with, put that email and phone on the load wherever you advertise it (load boards, emails), so carrier calls and replies reach Lanesurf. It comes back only when Lanesurf has set a posting email and phone for your key. Keys made by signing in from an AI app don’t have one.

Read offers and pick a carrier

See Load status and offers.

Safe retries

Every load post needs an Idempotency-Key header (up to 200 characters; a new UUID per load). Without it you get 400 idempotency_key_required and nothing is created, because a retry after a timeout would otherwise create a second load and Lanesurf would contact the same carriers twice. Missing fields are reported first. Over MCP, send it as post_load’s idempotency_key. The key is scoped to the API key that sends it:

Call	Answer
First post with a key	`201`, a new `load_id`
Retry with the same key and the same load, from the same API key	`200`, the original load with its current `status` (`sourcing`, `covered`, …). No second load
Same key, same API key, but a different load	`422 idempotency_key_reused`. Nothing is created or changed. Use a new key
Retry while the first post is still running	`409 idempotency_in_progress` with `Retry-After: 5`. Wait, then retry with the same key and load
Same key from a different API key, even at the same brokerage	`201`, a different load
Post with no key	`400 idempotency_key_required`. Nothing is created

A 200 retry answers with the original load as it is now:

{
  "status": "covered",
  "load_id": "3f2a…",
  "tms_id": "api-7c1e…",
  "post_with": { "email": "jane@loads.example.com", "phone": "+14155550100" },
  "message": "This Idempotency-Key was already used for this load: this is the original load, not a new one. Check GET /v1/loads/3f2a…."
}

Use a new key for each new load. A used key can’t be used to change a load.

Commodity defaults to “General freight” and rate is optional. Numbers can be sent as numbers or strings (40000, "40000" or "$40,000"). A value that isn’t a number is refused with invalid_request naming the field, and nothing is posted.

Guides

Sign-up and setup API

Loads API

Safe retries

​Safe retries

Safe retries