Skip to main content
POST
Post a load
Send the load as JSON fields (the LoadFields schema). The minimum is: equipment_type, the first origin’s city, state and pickup_ready_date, and the last destination’s city, state and delivery_ready_date. Commodity defaults to “General freight” (returned in assumed). Rate is optional. Numbers may be sent as numbers or strings; one that isn’t a number answers 400. If something required is missing you get 422 missing_fields with a missing list of exact field paths (e.g. destinations[0].delivery_ready_date). Ask the person only for those, then send the whole load again. When the load is complete you get 201 with status: sourcing and a load_id. Lanesurf starts reaching carriers. post_with, when the answer has it, is the email and phone to put on the load wherever it is advertised, so carrier 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 yet. A brokerage that signed up through the API starts with carrier outreach off: its loads are saved with status: stalled and a status_reason saying outreach starts after Lanesurf’s review. Every reply, and the missing_fields error, has next_step: what the agent should do next. Retries. The Idempotency-Key header is required (up to 200 characters; a new UUID per load). Without it the post is refused with 400 idempotency_key_required, because a retry after a timeout would otherwise create a second load and Lanesurf would contact the same carriers twice. The key is scoped to the API key that sends it. With the same API key and the same Idempotency-Key:
  • First post: 201, a new load.
  • Retry with the same load: 200 with the original load and its current status (sourcing, covered, …). No second load.
  • Retry with a different load: 422 idempotency_key_reused. Nothing is created or changed.
  • Retry while the first post is still running: 409 idempotency_in_progress with Retry-After: 5. Wait, then retry.
The same Idempotency-Key from a different API key, even at the same brokerage, creates a different load. Use a new key for each new load.

Authorizations

Authorization
string
header
required

One key per broker rep or per carrier signup. Keep it secret.

Headers

Idempotency-Key
string
required

Required. Any string up to 200 characters, unique per load (a UUID works). Scoped to the API key that sends it. A retry of the same load with the same key from the same API key answers 200 with the original load, so a retry never creates a second one. A different load with a used key answers 422 idempotency_key_reused; a retry while the first post is still running answers 409 idempotency_in_progress. The same key from a different API key, even at the same brokerage, creates a different load.

Maximum string length: 200
Example:

"6b1f0c2e-load-4471"

Body

application/json

A load as fields. Required: equipment_type, the first origin's city, state and pickup_ready_date (or pickup_by_date), and the last destination's city, state and delivery_ready_date (or delivery_by_date). Fields typed string-or-number accept either (40000 or "40000"; $ and , are ignored). A value that isn't a number ("about 1250") answers 400 invalid_request naming the field; nothing is posted.

equipment_type
string
required

e.g. Dry Van, Reefer, Flatbed, Step Deck.

Example:

"Dry Van"

origins
object[]
required

Pickup stops, in order.

Minimum array length: 1
destinations
object[]
required

Delivery stops, in order.

Minimum array length: 1
weight_lbs
Example:

40000

commodity
string

Defaults to "General freight".

rate_min

Posted rate. If only one of rate_min / rate_max is given it is used for both.

rate_max

Most the broker will pay.

currency
string

USD, CAD or MXN (any letter case). Over REST any other value is ignored, not rejected; the MCP tool's schema allows only these three.

Example:

"USD"

temperature

Reefer setpoint (°F).

is_palletized
boolean
pallet_count
driver_requirements
string

Say "team" for a team load. Other text is not used.

special_requirements
string

Used as the special instructions when explicit_special_instructions is empty.

explicit_special_instructions
string

Special instructions for carriers.

reference_number
string

Your own load number (your TMS or customer reference). Shown on the load and in the Lanesurf dashboard.

Maximum string length: 100
Example:

"PO-4471"

Response

A retry of the same load with an Idempotency-Key this API key already used. This is the original load with its current status; no second load was created. assumed is not set.

status
enum<string>
required

A new load is sourcing, or stalled when the brokerage signed up through the API and Lanesurf hasn't turned carrier outreach on yet (status_reason says so). On an Idempotency-Key retry (200) this is the original load's current status; see LoadStatus.

Available options:
sourcing,
stalled,
covered,
inactive,
deleted
load_id
string<uuid>
required
next_step
string
required

For the agent. Exactly what to do next and which MCP tool to call (REST path in brackets).

tms_id
string

Lanesurf's name for the load (starts with api-). Works in place of load_id in /v1/loads/{id}.

Example:

"api-7c1e0b5a2f4d4c8e9a3b6d1f0e2c4a8b"

post_with
object

The email and phone to put on the load wherever it is advertised, so carrier replies reach Lanesurf. Only set when Lanesurf has set a posting email and phone for the key; keys made by signing in from an AI app don't have one yet.

assumed
object

Values Lanesurf filled in because they weren't given (e.g. commodity). Not set on a retry.

message
string

What happens next, for people. On an Idempotency-Key retry it says the key was already used for this load and this is the original load, not a new one.

status_reason
string

Set when status is stalled.

Example:

"Carrier outreach starts after Lanesurf's review of your brokerage. This load is saved and starts sourcing once outreach is on; nothing to do until then."