CRM Overview

The Beeving CRM lets you manage your sales pipeline directly from the API.

Concepts

Contact ─────┐
             ├──→ Lead ──→ Deal (in a pipeline stage)
Company ─────┘     │         │
                   └─────────┴──→ Task

Resource	Description
Company	A business entity. Can have multiple contacts, leads and deals.
Lead	A qualified prospect linked to a contact. Score calculated automatically from email engagement.
Deal	A sales opportunity with amount and close date. Moves through pipeline stages.
Task	An action item linked to a contact, lead, deal or company.
DealStage	A pipeline stage (e.g. Prospect, Proposal, Negotiation, Won).

Lead Scoring

A lead's score is calculated automatically from email engagement:

score = (opens × points_per_open)
      + (clicks × points_per_click)
      + (replies × points_per_reply)

Scoring coefficients are configurable per workspace in CRM settings.

When a lead reaches the conversion threshold (lead_conversion_threshold), it can be automatically converted to a deal.

To recalculate manually:

curl -X POST https://app.beeving.com/api/v1/crm/leads/42/recalculate-score \
  -H "Authorization: Bearer TOKEN"

Typical Workflow

1. Create a company
   POST /crm/companies

2. Create a contact linked to the company
   POST /contacts  { company_id: 1 }

3. Create a lead from the contact
   POST /crm/leads  { contact_id: 7, source: "inbound" }

4. Send campaigns → score increases automatically

5. Convert the lead to a deal
   POST /crm/leads/7/convert  { deal_name: "...", stage_id: 1 }

6. Move the deal through the pipeline
   PUT /crm/deals/3  { stage_id: 2 }

7. Mark as won
   POST /crm/deals/3/won