# Get leads (v1)

> POST /agents/:id/leads to capture a lead and GET /agents/:id/leads to read the inbox. Capture fires the lead.created webhook.

Capture and read leads collected by an agent. Capturing a lead fires the `lead.created` [webhook](/docs/integrations/webhooks) so your CRM or automation can pick it up.

## POST /agents/:id/leads

Public capture endpoint (used by the widget runtime, and callable from your backend). At least one of `email`, `phone`, or `name` is required.

| Field | In | Type | Notes |
| --- | --- | --- | --- |
| id | path | integer | The agent id. |
| fields | body | object | A free-form object of lead fields. If omitted, top-level `email` / `name` / `phone` are used to build it. |
| email | body | string | Convenience field, folded into `fields`. One of email/phone/name required. |
| name | body | string | Convenience field. |
| phone | body | string | Convenience field. |
| conversationId | body | integer | Optional conversation this lead came from. |

```bash
curl https://app.bookbag.ai/agents/123/leads \
  -H "Authorization: Bearer $BOOKBAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fields": { "email": "sam@acme.com", "name": "Sam" }, "conversationId": 456 }'
```

## GET /agents/:id/leads

Read the lead inbox for an agent (newest first). Each lead's captured `fields` are returned as a parsed object.

```bash
curl https://app.bookbag.ai/agents/123/leads \
  -H "Authorization: Bearer $BOOKBAG_API_KEY"
```

> **TIP:** A CSV export of all leads is available at `GET /agents/:id/leads/export` and downloads a file with one column per field seen across leads.

## Status codes

| Status | Meaning |
| --- | --- |
| 200 | Success. |
| 400 | No usable lead field provided. Body: `{ success:false, error:{ code:"validation_error", message } }`. |
| 401 | Missing or invalid credentials (reads). |
| 404 | Agent not found. |

See [Errors](/docs/api/errors).