> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lanesurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> You are reading the Lanesurf Agent API docs. Start with /for-ai-agents.md for the rules an agent must follow.
> The API is at https://agent.lanesurf.com and the MCP server at https://agent.lanesurf.com/mcp. Lanesurf doesn't send webhooks: poll.
> Limits: /rate-limits.md. Keys: /api-keys.md. Safe retries: /idempotency.md. Every route on one page: /api-reference.md.
> Always confirm with the person before accepting a carrier offer or bidding on a load. Never reveal an API key, and never show broker contact details to a carrier.
> The full contract is at /openapi.yaml.
> Sign up with POST /v1/signup (carrier or broker, a work email, an MC and/or DOT number), then POST /v1/signup/{signup_id}/verify. Follow next_step on every signup answer.

# Sign up

> Get a carrier API key with your MC or DOT number, your work email and an 8-digit code. No one at Lanesurf involved.

A carrier or dispatcher can get a key with no human at Lanesurf involved. The agent does the calls;
the person only reads out a code. Every reply, including errors, has `next_step`: what the agent should
do next.

**1. Start with your MC or DOT number and work email**

Send `role: "carrier"`, the carrier's MC **and/or** DOT number, and your **work email** at the carrier.

```bash theme={null}
curl -X POST https://agent.lanesurf.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"role": "carrier", "dot_number": "1234567", "email": "dispatch@exampletrucking.example.com"}'
```

* **Work email only.** Gmail, Yahoo, Outlook, Hotmail, Live, MSN, iCloud, me.com, mac.com, AOL, Proton,
  GMX, Zoho, Yandex and mail.com are refused with `400 invalid_request` ("use your work email").
* **Email is required.** There is no signup by phone.

Lanesurf emails an 8-digit code. The reply only says where it went:

```json theme={null}
{
  "signup_id": "5d0e…",
  "role": "carrier",
  "channel": "email",
  "sent_to": "d*******@exampletrucking.example.com",
  "expires_at": "2026-10-23T14:10:00Z",
  "next_step": "Ask the person for the 8-digit code we emailed to d*******@exampletrucking.example.com, then call verify_signup with signup_id and code (POST /v1/signup/{signup_id}/verify). The code expires in 10 minutes."
}
```

**2. Ask the person for the code**

Tell them where it went (`sent_to`) and ask for the 8 digits. Codes expire after **10 minutes** and
allow **5 attempts**.

**3. Verify and get the key**

```bash theme={null}
curl -X POST https://agent.lanesurf.com/v1/signup/$SIGNUP_ID/verify \
  -H "Content-Type: application/json" \
  -d '{"code": "48291307"}'
```

```json theme={null}
{
  "api_key": "ls_live_…",
  "principal": {
    "key_id": "0b1c…",
    "key_prefix": "ls_live_1a2b",
    "role": "carrier",
    "verification": "verified",
    "carrier": { "legal_name": "EXAMPLE TRUCKING LLC", "mc_number": "123456", "dot_number": "1234567",
                 "contact_email": "dispatch@exampletrucking.example.com" }
  },
  "next_step": "Give the person api_key now to store securely … Post its available trucks with post_truck, save the lanes it runs with save_lane, then find loads with truck_matches or search_loads and bid with bid_on_load."
}
```

The key is shown **once**. Store it securely right away. If the reply was lost on the way, verify again
with the same code while it's still valid.

## Verified or needs review

Lanesurf checks the carrier by DOT (or MC) number and compares your email's **domain** with the email
addresses on the carrier's record. When that check confirms you, the key is `verified` straight away.
Otherwise the carrier account starts **under review** and Lanesurf's team verifies it. You only learn the
result from the **verify** reply, after you've proved the inbox with the code.

| `verification` | When | What the key can do |
| - | - | - |
| `verified` | The automatic check confirmed you: your email's domain is exactly the domain of an email on the carrier's record (for example `you@exampletrucking.example.com` and `dispatch@exampletrucking.example.com`), and the record doesn't show the carrier's authority as inactive (or a broker-only authority). Or Lanesurf's team verified the account | Everything: trucks, lanes, load search, load details, truck matches, **bids** |
| `needs_review` | The automatic check couldn't confirm you: a different domain, no carrier found, no email on the record, inactive authority, or the check wasn't available. A shared mailbox domain (ISP mail such as att.net or comcast.net, other free mail, disposable inboxes) never counts as a match, because anyone can hold a mailbox there | Your carrier account is under review. Post and manage trucks and lanes, and list your own bids. **No** load search, load details, truck matches, outreach or bids (`403 verification_required`) until Lanesurf verifies it |

Nobody is refused for not matching. A needs-review reply looks like this:

```json theme={null}
{
  "api_key": "ls_live_…",
  "principal": { "role": "carrier", "verification": "needs_review", "…": "…" },
  "message": "your carrier account is under review; until Lanesurf verifies it you can manage trucks and lanes and list your bids, but you can't search loads, view loads, get matches or bid",
  "next_step": "… Meanwhile post trucks with post_truck, save lanes with save_lane and follow bids with list_bids. Call whoami later to see when verification changes to verified."
}
```

**Under review is not a rejection.** Lanesurf reviews carriers that weren't verified automatically and can
verify them by hand (for example after a call with the dispatcher). The same key then gets full access; nothing
to redo. To speed it up, email [support@lanesurf.com](mailto:support@lanesurf.com) from your work email with your MC or DOT number.

Check where you stand any time with [`GET /v1/me`](https://docs.lanesurf.com/authentication#check-a-key).

## Limits

Starting signup is limited to 5 times per email per hour and 10 per day, 10 per MC/DOT number per day,
and per-IP limits on both start and verify. Once you have a key, every authenticated `/v1` route is
limited to 120 requests per minute per key (counted on each Lanesurf server, so treat it as the most to send). Over any limit you get `429 rate_limited` with `Retry-After`.

## When something goes wrong

Every error has `code` and `next_step`.

| HTTP | `code` | What to do |
| - | - | - |
| `400` | `invalid_request` | Fix the request: a work email (not free mail), digits for MC/DOT, an 8-digit code |
| `422` | `missing_fields` | `missing` lists what to ask for (`role`, `email`, `mc_number or dot_number`) |
| `404` | `not_found` | No such signup. Check the `signup_id` |
| `410` | `signup_expired` | The code expired or ran out of attempts. Start again from step 1 |
| `409` | `already_redeemed` | This signup was already completed and its key is in use. If the key is lost, start again from step 1 |
| `422` | `invalid_code` | Wrong code. The message says how many attempts are left |
| `429` | `rate_limited` | Too many tries. Wait `Retry-After` seconds |
| `503` | `unavailable` | Code sending or a Lanesurf system is down. Try later (wait `Retry-After` when set) |
| `500` | `internal` | Unexpected error. Try later |

Then [find a load](https://docs.lanesurf.com/carriers/find-a-load.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.