Lead management

Leads are top-of-funnel records — people or companies that have shown some interest but are not yet qualified accounts. BottleCRM tracks leads through capture, qualification, and conversion.

Capturing leads

Three intake paths are supported out of the box:

  1. Manual entry in the web app at /leads/new.
  2. CSV upload via POST /api/leads/upload/ — the parser de-duplicates on email and reports row-by-row errors instead of failing the whole batch.
  3. API ingestion — POST /api/leads/ from a website form, a marketing tool, or a script.

The list view supports filtering by status, source, assignee, and any filterable custom field.

Lead lifecycle

A lead's status walks through:

new → assigned → contacted → qualified  →  converted
                                       ↘   lost

Status transitions are validated server-side — you cannot mark a lost lead as converted by hacking the UI. When a lead is converted, the system creates a matching Account, Contact, and (optionally) Opportunity in one transaction.

Kanban view

/leads/kanban shows leads grouped by status. Drag a card between columns to update its status; the backend re-validates the transition and returns the canonical record so the UI can confirm or roll back.

Bulk operations

The list view supports multi-select for: assigning to a teammate, tagging, deleting, and exporting. Each bulk operation hits a dedicated endpoint that paginates the work and respects RLS.

See also

  • Custom fields — add organization-specific data to leads.
  • Leads API — full endpoint reference with examples.