Leads, customers, and lifecycle continuity

Core endpoints

• POST /v1/leads — capture a lead
• GET /v1/leads — list with filters (status, source, unassigned, age)
• POST /v1/leads/{id}/convert — convert a qualified lead to a customer
• GET /v1/customers/{id} — full customer record with lifecycle history

Capturing a lead

curl -X POST https://api.urbld.com/v1/leads \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Homeowner",
    "phone": "+15551234567",
    "email": "jane@example.com",
    "source": "website_form",
    "service_needed": "hvac_repair",
    "address": "123 Elm St, Austin, TX 78701",
    "notes": "AC unit not cooling; unit is ~10 years old."
  }'

The response includes the new lead_id, lifecycle_number, and a duplicate_of field when the server detected a likely match against an existing record.

Converting to a customer

await fetch(`https://api.urbld.com/v1/leads/${leadId}/convert`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
});

The customer inherits the lead's lifecycle_number. Every future job, invoice, and communication is threaded under the same ID.

Design principles

• Never hard-delete. Leads and jobs are the most critical entities in the platform; loss is non-recoverable. Use DELETE /v1/leads/{id} — it sets deleted_at only.
• Tenant isolation. Every list endpoint is implicitly scoped to the token's organization. There is no cross-org list.
• Actionable leads only. The intake standard rejects leads that fail minimum data-point validation (at least one contact channel + service intent).