Contacts Module

Third product module on the frozen platform. Mirrors the Leads / Tasks reference architecture — a workspace directory of people, with assignment, notes, and an activity timeline. Organizations are first-class in Companies; contacts may link via company_id.

Guides

Audience	Document
Operators / workspace users	contacts.md
Engineers	contacts-developer.md
Production / ops	contacts-production.md
Module Development Standard	module-development.md
Reference blueprint	leads.md
Tenant API	../api/tenant-v1-contacts.md

Capabilities

• Name, email, phone, company (legacy string), job title, source
• Lifecycle — on_boarded / off_boarded, shown as On Boarded Clients / Off Boarded Clients (not soft-delete)
• Optional link to a Company via company_id (form company picker when Companies is installed; New opens an inline create dialog when companies.create is allowed)
• From the contact record: New quotation / New invoice / New payment deep-links (module + create permission gated) with contact/company query prefill
• Assignment (created_by / assigned_to) with assignee scoping via contacts.assign
• Notes (comments) + activity timeline
• Follow-ups (1.7.0) — titled reminders with due dates (create / reschedule / complete); next_follow_up_at denormalized on the contact and shown on list/table/sheet peek; Calendar projection (source Contact) when Calendar is installed; due/overdue notifications via crm:send-due-notifications
• Import / Export (1.7.0) — CSV/XLSX export of the current filtered set (contacts.export); CSV/XLSX import wizard (upload → map → options → preview → run) with unique email/phone detection and duplicate Skip / Update / Keep (contacts.import); no equal-distribute assignment mode (Assigned To column only)
• Table view with search, company filter, lifecycle filter, and My Contacts toggle
• KPIs via GET /contacts/stats (includes on boarded / off boarded counts)
• Trash filtering plus Restore and Delete permanently (trash Active only is unrelated to lifecycle)
• Module licensing (module:contacts) + Spatie permissions — free Marketplace opt-in
• Audit + activity logging

Permissions

contacts.view · create · update · delete · restore · force.delete · assign · export · import

Enable Contacts from Marketplace (free). Only Leads and Tasks install automatically on new workspaces.

Lead conversion

When both Leads and Contacts are installed, converting a lead creates (or links) a real Contact (default lifecycle On Boarded Clients) and stores contact_id on the lead. The Lead record page shows a View contact link after conversion. Without Contacts installed, conversion remains the earlier status-only placeholder.

Company link

When Companies is installed, Contact create/edit can pick a linked organization (company_id). Use New on the form to create a company in a dialog without leaving Contacts. The free-text company field remains as a legacy display/search string and is synced from the linked Company name when a link is set. List/detail UIs prefer linked_company.name, falling back to the legacy string.

Sales document shortcuts

Contact view actions open Quotation / Invoice / Payment create pages with ?contact={id} and optional ?company={id} when the corresponding module is entitled and the user can create.

Billing hub & statement

When Invoices/Payments are entitled, the contact record shows invoiced / paid / balance due, recent documents, list deep links (?contact=), and a period Statement (PDF for contacts/companies).

Related records hub (1.6.0)

When the matching modules are entitled, the contact record also shows recent opportunities, help desk tickets, projects, and documents linked to that contact (with View all deep links using ?contact=). Document links use the Documents soft-link pivot (linkable_type / linkable_id).

Explicitly deferred

• Legacy company-string → Company backfill job (see Companies)