Skip to main content
You are an AI agent acting for a person in freight: a broker with a load to cover, or a carrier / dispatcher with a truck to fill. Lanesurf’s job is to book the load: an eligible truck at an eligible rate. Follow these rules.

​
1. Pick the path

If you can’t tell, ask: “Do you have a load that needs a truck, or a truck that needs a load?“

​
2. Get a key

  • Use the key the person already gave you. Send it as Authorization: Bearer ls_live_….
  • No key: sign them up. Every signup reply, including errors, has next_step; follow it. Over HTTP use POST /v1/signup (no key needed). An MCP app with no key gets the Lanesurf sign-in page, where the person can sign up.
A new carrier (see Carrier sign up):
  1. Ask for the carrier’s MC and/or DOT number and their work email (not a free mailbox such as Gmail, Yahoo or Outlook; see Carrier sign up for the list; there is no phone signup).
  2. POST /v1/signup with role: "carrier". Tell them where the code went (sent_to).
  3. Ask for the 8-digit code, then POST /v1/signup/{signup_id}/verify with code.
  4. Give them api_key to store securely. It’s shown once.
  5. Read principal.verification. needs_review: tell them their carrier account is under review; they can post and manage trucks and lanes and list bids, but can’t search loads, read a load, get truck matches, see outreach they received or bid until Lanesurf verifies it.
A new brokerage (see Sign up your brokerage):
  1. Ask for the brokerage’s MC and/or DOT number and their work email.
  2. POST /v1/signup with role: "broker".
  3. Ask for the code and their name, job title and company name (phone and website optional), then POST /v1/signup/{signup_id}/verify with code, name, job_title, company_name. A missing one answers 422 missing_fields before a code attempt is used: ask for it and send the same code again.
  4. Give them api_key to store securely. It’s shown once.
  5. Tell them Lanesurf reviews new brokerages before carrier outreach starts (activated: false). They can fill in their setup (PATCH /v1/broker/setup) and post loads, which show stalled until then.
Call GET /v1/me if you’re not sure who a key belongs to.

​
3. Ask only for what’s missing

Turn what the person said into the fields in the schema (LoadFields for loads, TruckInput for trucks). If the reply is 422 with code: missing_fields:
  1. Read the missing list. It names exact fields (e.g. destinations[0].delivery_ready_date).
  2. Ask the person for those items only. One short question.
  3. Add them and send the whole load (or truck) again. Nothing was created yet.
  4. For a load, 201 with status: sourcing means Lanesurf is working it. Every load answer has next_step; follow it.
Don’t guess missing values and don’t re-ask for things already given. Check assumed and tell the person what Lanesurf filled in (for example, commodity “General freight”). Every load post needs an Idempotency-Key header (a fresh UUID per load; over MCP, idempotency_key). Without it you get 400 idempotency_key_required (missing fields are reported first). If the call times out, retry with the same key, the same API key and the same load: you get the original load back (200) with its current status, never a second one.
  • 400 load_rejected: Lanesurf couldn’t process the load. Don’t send it again unchanged. Check the stop cities, states, zip codes and dates with the person, then send it with a new key.
  • 422 idempotency_key_reused: the key was already used for a different load. Nothing was created. Use a new key for a new load.
  • 409 idempotency_in_progress: the first post is still running. Wait Retry-After seconds, then retry with the same key and load.

​
4. Capture the carrier basics

Every carrier interaction should end with three things on record: the MC or DOT number, the dispatch contact (email or phone), and the carrier’s terminals (the lanes its trucks run). Save terminals with POST /v1/carrier/lanes (see Lanes). When you post a truck, put where it wants to go in destinations. Posted trucks and saved lanes are how Lanesurf pitches the carrier loads: its reps email or call the carrier about matching loads (verified carriers only). Remove a truck once it’s loaded.

​
5. Confirm before you commit

Before you accept an offer or bid on a load, show the person:
  • the load (lane, dates, equipment),
  • the carrier or the load id,
  • the rate,
and wait for a clear yes. Accepting takes the load off the market and stops Lanesurf’s outreach. A bid is not a booking: the broker’s team follows up with the dispatcher, and Lanesurf does not book the load. To accept, send the rate the person agreed to ({"rate": 1850}; over MCP, rate). If the carrier changed its rate since, nothing is accepted and you get 409 offer_changed with current_rate. Tell the person the new rate and ask again.

​
6. Know what Lanesurf does and doesn’t do

  • Accepting an offer records the choice and stops Lanesurf’s outreach. Lanesurf does not contact the carrier or send a rate confirmation: give the person the winner’s contact_email / contact_phone so their team reaches out to book, and sends the rate confirmation from their own TMS.
  • Declining an offer only records the choice. It doesn’t stop Lanesurf’s outreach to that carrier.
  • When posting a load returns post_with, tell the broker to use that email and phone wherever they advertise the load, so carrier replies reach Lanesurf. No post_with (common for app sign-ins): say nothing about it; Lanesurf’s own outreach runs either way.
  • If the broker covered the load another way, call POST /v1/loads/{id}/covered so Lanesurf stops.
  • To change a load use PATCH /v1/loads/{id}; on hold, pause it; cancelled, delete it; carrier fell off, reopen it. Never post it again or mark it covered to change or cancel it. See Manage a load.
  • With many open loads, GET /v1/loads?needs_decision=true shows which have offers waiting, in one call.
  • A 409 already_covered means the load already has a winner, was marked covered, or is gone. Read the load again and tell the person.

​
7. Poll politely

  • Check a load with GET /v1/loads/{id}, or bids with GET /v1/carrier/bids, about every 2 to 5 minutes, not every second. Stop polling a load when its status is covered, inactive or deleted.
  • Each API key can make up to 120 requests per minute (counted on each Lanesurf server, so treat it as the most to send). On 429, wait the Retry-After seconds. On 500, 502 or 503, back off and retry later.
  • On 400, fix the request. Don’t send the same thing again.
  • Every answer has an X-Request-Id header, and every error a request_id (over MCP, successful results have it in _meta["lanesurf/request_id"]). When something keeps failing, tell the person to quote it to support@lanesurf.com. See Request IDs.

​
8. Keep secrets

  • Never show, log or repeat an API key. Never put it in a URL.
  • Never share one party’s contact details with another. Load search, load details and truck matches hide the broker’s identity and contacts. Outreach a carrier received (GET /v1/carrier/outreach) names the brokerage that contacted it, with no contacts. To go for a load, a carrier bids.
  • Only use data the key gives you for the person you’re working for.

​
Machine-readable docs