> ## 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 your brokerage

> Get a broker API key yourself with your MC or DOT number, your work email and an 8-digit code.

A brokerage can sign up through its AI agent. Lanesurf then reviews it and turns on carrier outreach.
Every reply, including errors, has `next_step`: what the agent should do next. (Already working with
Lanesurf? Don't sign up; that answers `409 existing_customer`. Your Lanesurf admin or account manager
gives you access.)

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

```bash theme={null}
curl -X POST https://agent.lanesurf.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"role": "broker", "mc_number": "654321", "email": "dana@acmefreight.example.com"}'
```

Give the MC **and/or** DOT number. Use your **work email**: Gmail, Yahoo, Outlook, Hotmail, Live, MSN, iCloud (and me.com, mac.com), AOL, Proton, GMX, Zoho, Yandex and mail.com addresses, including country versions such as yahoo.co.uk or gmx.de,
are refused with `400 invalid_request` ("use your work email"). Lanesurf emails an 8-digit code; the reply has a `signup_id`.

**2. Verify with the code and who you are**

```bash theme={null}
curl -X POST https://agent.lanesurf.com/v1/signup/$SIGNUP_ID/verify \
  -H "Content-Type: application/json" \
  -d '{"code": "48291307", "name": "Dana Reyes", "job_title": "Carrier Sales Manager",
       "company_name": "Acme Freight LLC", "phone": "+12145550100", "website": "https://acmefreight.example.com"}'
```

| Field | Required | Notes |
| - | - | - |
| `code` | Yes | The 8 digits from the email |
| `name` | Yes | Your full name |
| `job_title` | Yes | Your role at the brokerage, up to 100 characters |
| `company_name` | Yes | The brokerage's name as carriers should hear it, up to 200 characters |
| `phone` | No | E.164; a 10-digit US number works |
| `website` | No | http(s), up to 300 characters; `https://` is added if you leave it out |

The MC/DOT number and the email come from step 1. If a required field is missing you get
`422 missing_fields` with a `missing` list **before** a code attempt is used: ask for those and send the
same code again.

```json theme={null}
{
  "api_key": "ls_live_…",
  "principal": { "role": "broker", "broker_id": "6a7b…", "rep_name": "Dana Reyes", "…": "…" },
  "activated": false,
  "message": "Lanesurf reviews new brokerages before carrier outreach starts; loads you post are saved and start sourcing once outreach is on",
  "next_step": "Give the person api_key now to store securely … Meanwhile review the brokerage setup with get_broker_setup and fill in working hours, payment terms and CC emails with update_broker_setup."
}
```

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. Other answers:

| Error | When |
| - | - |
| `409 existing_customer` | The company already uses Lanesurf. Don't sign up: their Lanesurf admin or account manager gives them access |
| `409 already_redeemed` | This signup was already completed and its key is in use. A lost key: contact [support@lanesurf.com](mailto:support@lanesurf.com) with the `request_id` |

**3. Lanesurf reviews, then turns outreach on**

A new brokerage starts with carrier outreach **off** (`activated: false`). You can post loads right away:
they're saved and show `stalled` with `status_reason` "Carrier outreach starts after Lanesurf's review…".
Once Lanesurf turns outreach on, they start sourcing.

## Your setup

`GET /v1/broker/setup` shows what Lanesurf's agents tell carriers about your brokerage and whether
outreach is on. `PATCH /v1/broker/setup` changes only these fields; anything else answers `400`:

| Field | What it is |
| - | - |
| `company_name` | The name the agents use with carriers |
| `working_hours` | e.g. "Mon-Fri 7am-6pm CT" |
| `payment_terms` | e.g. "Net 30; quick pay 2%" |
| `cc_emails` | Who is copied on carrier email threads (up to 10; replaces the list) |
| `ask_first_pricing` | `true`: the agents ask the carrier for their rate before quoting one |
| `loads_visible_to_carriers` | `true`: carriers' AI agents can find your loads and bid on them through the API. Off until you turn it on |

```bash theme={null}
curl -X PATCH https://agent.lanesurf.com/v1/broker/setup \
  -H "Authorization: Bearer ls_live_..." -H "Content-Type: application/json" \
  -d '{"working_hours": "Mon-Fri 7am-6pm CT", "payment_terms": "Net 30"}'
```

A change shows on the very next read: `PATCH` answers with what was saved, and `GET /v1/broker/setup`
reads it fresh.

Carrier outreach can't be switched on through the API; Lanesurf does that after review. A `company_name` that another Lanesurf brokerage already uses answers `409 broker_name_taken`.

Lanesurf's own outreach (email and calls to carriers) doesn't depend on `loads_visible_to_carriers`. That
field only decides whether carriers' AI agents see your loads in their search.

## What a broker key reaches

A broker key reaches `/v1/loads/*` and `/v1/broker/setup`: only the loads your brokerage posted
**through this API**, whichever of its reps posted them. Never loads from your TMS or from other
brokerages. A broker key on a carrier route gets `403 wrong_role`. `GET /v1/me` gives the brokerage id and
the rep the key belongs to; `GET /v1/broker/setup` has the brokerage's name. Then [cover a load](https://docs.lanesurf.com/brokers/cover-a-load.md).

> [!WARNING]
>
> Treat the key like a password. Don't paste it into shared chats, logs or prompts, and never show it back to the person after it's stored.


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