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.

View as Markdown

Capture and read leads collected by an agent. Capturing a lead fires the lead.created webhook 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.

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 }'

const res = await fetch("https://app.bookbag.ai/agents/123/leads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOOKBAG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ fields: { email: "sam@acme.com", name: "Sam" } }),
});
const { lead } = await res.json();

{ "success": true, "lead": { "id": 42 } }

GET /agents/:id/leads

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

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

{
  "success": true,
  "leads": [
    {
      "id": 42,
      "fields": { "email": "sam@acme.com", "name": "Sam" },
      "conversation_id": 456,
      "created_at": "1717286400000"
    }
  ]
}

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.

Chat with an agent

Create contacts