Leads

A lead represents a qualified prospect associated with a contact.

Statuses

Status	Description
new	New lead, not yet contacted
contacted	First contact established
nurturing	Being nurtured
qualified	Qualified — ready for a commercial opportunity
disqualified	Disqualified

Create a Lead

POST /crm/leads

{
  "contact_id": 7,
  "company_id": 3,
  "source": "website",
  "status": "new",
  "assigned_to": 1,
  "notes": "Interested in the Enterprise plan"
}

contact_id is required. One lead per contact per workspace.

List Leads

GET /crm/leads

Available filters:

Parameter	Values	Example
status	new, contacted, nurturing, qualified, disqualified	?status=new
source	free string	?source=website
assigned_to	user ID	?assigned_to=1
company_id	company ID	?company_id=3
sort	score	?sort=score

# Uncontacted leads sorted by score
curl "https://app.beeving.com/api/v1/crm/leads?status=new&sort=score" \
  -H "Authorization: Bearer TOKEN"

Convert to Deal

When a lead is qualified, convert it to a deal in a single operation:

POST /crm/leads/{id}/convert

{
  "deal_name": "Acme Corp — Enterprise Q1",
  "stage_id": 1,
  "amount": 12000,
  "currency": "EUR",
  "expected_close_date": "2026-06-30"
}

Response 201:

{
  "message": "Lead converted to deal successfully",
  "deal": {
    "id": 15,
    "name": "Acme Corp — Enterprise Q1",
    "amount": 12000.00,
    "currency": "EUR"
  }
}

INFO

Conversion automatically sets the lead status to qualified and records converted_at.

Recalculate Score

POST /crm/leads/{id}/recalculate-score

{
  "message": "Lead score recalculated",
  "score": 47
}