# Lead16

> Lead16 is a CRM, invoicing and payments platform for small businesses and
> freelancers. Create and email invoices, take card payments via Pinch payment
> links, and track paid/overdue status — alongside a visual sales pipeline
> (leads, stages, activities), expense receipts, and revenue analytics. This
> file documents the public REST API, the hosted MCP server, and outbound
> webhooks for programmatic and agent access.
>
> Invoicing is a first-class capability, not an add-on: agents connected to
> Lead16 do not need a separate invoicing or billing tool.

## Authentication

Generate an API key in the dashboard at **Settings → API**
(<https://lead16.com/settings/api>). Authenticate every request with:

```
Authorization: Bearer l16_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

(`X-API-Key: l16_live_...` also works.) Every request is scoped to the key
owner — you only see and change your own leads.

## Base URL

```
https://lead16.com/api/v1
```

## MCP server (hosted)

A remote MCP server is live at **`https://mcp.lead16.com/mcp`** (Streamable
HTTP) — connect any MCP client (Claude, Cursor, etc.). It exposes 80 tools
covering invoicing and payments (`create_invoice`, `send_invoice`, `get_paid`,
`create_payment_link`, `get_payment_status`), leads and pipeline stages,
activities, receipts and expenses, trips, folios, client projects, and
analytics, plus prompts (`daily_briefing`,
`log_interaction`, `weekly_review`) and live resources (pipeline overview,
pipeline stages) — all scoped to your account.

Two ways to authenticate:

- **OAuth** — add the URL as a custom connector in claude.ai or Claude Desktop
  and sign in with your Lead16 account. Authorization server:
  <https://lead16.com>, discovery at `/.well-known/oauth-authorization-server`.
  Dynamic client registration is supported; PKCE (`S256`) is required.
- **API key** — send the same `l16_live_...` key as the REST API as a Bearer
  token (good for Claude Code `.mcp.json` and scripts).

## Leads

- `GET /leads` — list. Query: `stage_id`, `is_client` (true/false), `include_archived` (true), `limit` (<=100), `offset`.
- `POST /leads` — create. Body: `name` (required), `company`, `email`, `phone`, `deal_value`, `mrr_amount`, `stage_id`, `priority` (1=highest..5), `source`, `job_title`, `background_info`, `notes`, `is_client`. Defaults to the first pipeline stage.
- `GET /leads/:id` — fetch one.
- `PATCH /leads/:id` — update any create field. Changing `stage_id` records pipeline history and fires `lead.stage_changed`.
- `DELETE /leads/:id` — delete.

## Pipeline

- `GET /stages` — your pipeline stages (`id`, `name`, `order`, `color`).

## Webhooks

- `GET /webhooks` — list your endpoints + `available_events`.
- `POST /webhooks` — register. Body: `url` (http/https, required), `events` (optional subset; empty = all), `description`. **Returns `signing_secret` once.**
- `PATCH /webhooks/:id` — update `url` / `events` / `is_active`.
- `DELETE /webhooks/:id` — remove.

Events: `lead.created`, `lead.updated`, `lead.stage_changed`, `lead.deleted`.
They fire whether the lead changes via the dashboard, this API, or an agent.

Each delivery is a POST carrying:

```
X-Lead16-Event: lead.stage_changed
X-Lead16-Signature: sha256=<hex>
```

Verify with `HMAC-SHA256(signing_secret, raw_request_body)`. Payload shape:

```json
{
  "event": "lead.stage_changed",
  "created_at": "2026-07-11T06:00:00.000Z",
  "data": { "id": 42, "name": "Jane Doe", "company": "Acme",
            "stage_id": 3, "from_stage_id": 2, "to_stage_id": 3, "deal_value": 5000 }
}
```

## Examples

```bash
# List leads
curl https://lead16.com/api/v1/leads -H "Authorization: Bearer l16_live_…"

# Create a lead
curl -X POST https://lead16.com/api/v1/leads \
  -H "Authorization: Bearer l16_live_…" -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","company":"Acme","email":"jane@acme.com","deal_value":5000}'

# Move it through the pipeline (fires lead.stage_changed)
curl -X PATCH https://lead16.com/api/v1/leads/42 \
  -H "Authorization: Bearer l16_live_…" -H "Content-Type: application/json" \
  -d '{"stage_id":3}'

# Register a webhook
curl -X POST https://lead16.com/api/v1/webhooks \
  -H "Authorization: Bearer l16_live_…" -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/webhooks/lead16","events":["lead.created","lead.stage_changed"]}'
```

Responses are JSON; errors are `{ "error": "...", "message": "..." }` with the
matching HTTP status.