Leads

Overview

A lead is a prospect you have not yet qualified. It is lighter than a contact: a name, one way to reach them, where they came from, who owns the follow-up and what happens next. When a lead is worth pursuing, convert it — one call creates the contact, the company and (optionally) a deal, and links them back to the lead.

Leads move through a fixed status lifecycle. Quotes can be raised against a lead, and notes and tasks can be attached to one (entity_type: "lead", see Notes & Tasks).

Authentication

Authorization: Bearer cm_your_api_key

The lead object

{
  "id": "7a10…",
  "tenant_id": "a0b1…",
  "name": "Priya Nair",
  "email": "priya@acme.example",
  "phone": "+919800000000",
  "company_name": "Acme Traders",
  "job_title": "Operations Head",
  "source": "web_form",
  "status": "qualified",
  "owner_user_id": "b1f2…",
  "score": 40,
  "estimated_value_minor": 24000000,
  "currency": "INR",
  "next_follow_up_at": "2026-10-12T09:30:00Z",
  "last_contacted_at": "2026-10-08T11:00:00Z",
  "lost_reason": null,
  "message": "Need a voice agent for missed-call follow-ups.",
  "attribution": { "utm_source": "newsletter" },
  "external_ref": null,
  "converted_contact_id": null,
  "converted_company_id": null,
  "converted_deal_id": null,
  "converted_at": null,
  "created_at": "2026-10-07T09:00:00Z",
  "updated_at": "2026-10-08T11:00:00Z"
}

Status lifecycle

GET /api/v1/crm/leads

Newest first.

GET /api/v1/crm/leads/stats

Total and counts of your leads by status. Every status is present, with 0 when there are none.

{
  "total": 40,
  "by_status": {
    "new": 14,
    "contacted": 9,
    "qualified": 5,
    "unqualified": 3,
    "converted": 7,
    "lost": 2
  }
}

POST /api/v1/crm/leads

curl -X POST https://api.callmissed.com/api/v1/crm/leads \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Priya Nair",
    "email": "priya@acme.example",
    "company_name": "Acme Traders",
    "source": "referral",
    "estimated_value_minor": 24000000,
    "currency": "INR"
  }'

Returns 201 with the lead object. A reused external_ref returns 409. An owner_user_id outside your tenant returns 404.

GET / PATCH / DELETE /api/v1/crm/leads/{lead_id}

PATCH accepts every create field except external_ref, all optional. Explicit null is 422 for name, source, status, score and currency. Moving a lead to contacted stamps last_contacted_at with the current time unless you send it. Changing the status of a converted lead is 422. DELETE permanently deletes the lead and returns 204; contacts, companies and deals created by a conversion are kept.

Convert a lead

POST /api/v1/crm/leads/{lead_id}/convert

In one transaction: reuses a contact or creates one from the lead (an existing contact in your account with the same phone, then the same email, is reused), reuses a company with the same name (case-insensitive) or creates one when company_name is set, and optionally creates a deal. Sets the lead to converted, stamps converted_at and fills the three converted_* ids. The contact's lifecycle stage moves to opportunity when a deal is created, otherwise qualified, and is never moved backwards.

curl -X POST https://api.callmissed.com/api/v1/crm/leads/7a10…/convert \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "create_deal": true, "deal_title": "Acme — voice agents" }'

{
  "lead": { "id": "7a10…", "status": "converted", "converted_contact_id": "4411…", "converted_at": "2026-10-09T10:00:00Z", "…": "full lead object" },
  "contact_id": "4411…",
  "company_id": "5c6d…",
  "deal_id": "33cc…"
}

lead is the full lead object. company_id and deal_id are null when no company or deal was created or linked.

Converting a lead that is already converted returns 409, as does a new contact that would collide on phone or email. A pipeline_id, stage_id or existing_contact_id outside your tenant returns 404. With create_deal: true, 422 is returned when you have no pipeline (create one or send create_deal: false), the pipeline has no stages, the stage is outside the pipeline, or the deal value is too large.

Errors

Nothing on this page consumes credits.