CRM

Scope

CRM only helps if it stays tied to the real commercial record the business runs from. This guide keeps the public-safe workflow coverage and removes internal route and API detail.

Customer management, contacts, communication log, deals, and the CRM dashboard.

The CRM workspace is split into dedicated Pipeline, Forecasting, Activities, Customers, Contacts, and Risk & Health tabs so operators can stay inside one route without losing the workflow boundary between queue work, pipeline review, account work, and churn/capture exceptions. Queue priority and capture-review exceptions are explained directly in the UI so operators do not have to infer why something is next or unresolved.

CRM: Customers and Pipeline

Customer Lifecycle

Every customer has a lifecycle_stage that tracks their position in the sales funnel:

Customers start as prospect and advance through stages. When a deal is closed-won, the customer automatically transitions to customer. The health score (0-100) tracks customer satisfaction; scores below 30 flag churn risk.

Create a Customer

Fields: - name (required) – company/customer name - lifecycle_stage – defaults to prospect - lead_source – where the lead came from - billing_email – for invoicing

Health fields such as health_score are maintained after creation through customer updates and integrations rather than the initial create payload.

Account owner: Customer create and edit now use a searchable assignee lookup backed by active portal users in your tenant. If you do not pick a different owner, the customer defaults to you. Customer directory rows, the customer workspace, and churn-risk views all show the current account owner so managers can see who owns follow-up.

Manual duplicate review endpoint:

List Customers

Filters: - lifecycle_stage – filter by stage - health_min, health_max – filter by health score range - search – search by name (case-insensitive partial match) - include_inactive – include archived customers - limit, offset – pagination (default limit: 50, max: 200)

Total count is returned in the X-Total-Count response header.

The CRM customer workspace uses this paged endpoint directly. The UI shows the visible range and page so operators can tell when they are looking at a slice instead of the whole tenant.

Open a Customer Workspace

The primary account workflow is now the route-backed customer workspace:

Open it from the customer directory, pipeline customer links, tenant contacts, or the churn-risk panel.

The workspace replaces the old modal detail pattern and keeps the main CRM actions close to the account: - edit or archive the customer - add a contact - create or advance a deal - log communication - review the explicit account owner alongside the rest of the account posture

The workspace shows customer posture plus recent finance-native context in one place: - deals - contacts - communications - product-scoped subscription states and contract snapshots - invoice health and outstanding AR - payment activity - billing events

Recent sections are intentionally capped for responsiveness, but each section also shows truthful totals so you can tell when you are looking at a recent slice instead of the full account history.

Workspace deal rows also carry product identity so mixed-product account histories stay legible without a second lookup. The customer workspace now renders those rows with product badges, and the billing posture panel shows one card per current product contract instead of collapsing everything into a singleton subscription tile.

Export Customers to CSV

Returns a CSV file with all customer data. Supports lifecycle_stage and search filters.

Update a Customer

Partial update – only send fields you want to change.

Archived customers cannot be edited through PUT.

Archive a Customer

Requires keystone.crm.delete permission and a reason in the request body.

Archive is the normal operator path. It hides the customer from active CRM views but preserves the full audit and finance history. The API blocks archive if the customer still has open deals or an active subscription.

Delete a Customer

Requires keystone.crm.delete permission.

Hard delete is now a cleanup-only path. The customer must already be archived, and the API blocks deletion when linked CRM or finance history still exists.

Contacts

Contacts are people associated with a customer.

Tenant-wide contact search:

The contacts tab is now fully paged and search-backed. The total contact count shown in the UI is for the full tenant query, while the table rows reflect only the current page.

List contacts:

Create contact:

Fields: - name (required) - is_decision_maker – boolean - notes

Archived customers cannot accept new contacts.

Update contact:

Delete contact:

Activities & Next Actions

CRM now has a first-class activity queue for forward-looking work. This is separate from the communication log.

Activity workspace endpoints:

Use the Activities tab for the full tenant workspace: - your next-action queue - your overdue queue - a paged activity table with customer and optional deal context

The queue cards still call out that overdue rows are the exception queue, but the next-action queue is no longer due-date sorted only. Keystone now ranks that queue with a finance-native priority overlay: - fit reflects whether the account and opportunity are worth serious seller time - intent reflects whether the account is showing current buying or follow-up momentum - billing context only participates when your role can already view the relevant billing or finance data

Each queue row now shows: - the combined priority score plus fit and intent inputs - operator-readable positive or negative signals that explain the strongest ranking drivers - a next-best-action recommendation tied to current CRM and finance context - sequence eligibility with explicit blockers when the account should not enter the bounded follow-up path

This is still CRM guidance, not a new outbound engine. The sequence recommendation is read-only and intentionally refuses accounts that are already contracted, stuck in billing trouble, or missing enough opportunity context to justify templated follow-up.

The customer workspace reuses the same ranked activity rows, so you can see whether the account is a high-fit active opportunity, a billing exception that needs finance attention first, or a bad sequence candidate without leaving the CRM route.

Activity fields: - title (required) - description (optional) - due_date (required)

Owner defaults: If you link a deal, the activity owner defaults from the deal owner. Otherwise it defaults from the customer owner, and if neither exists it falls back to you.

Safety rules: - Archived customers cannot accept new activities. - Archived deals cannot accept linked activities. - Priority scoring and sequence guidance are computed from existing records only. Working the queue does not create hidden activity rows, outbound campaigns, or comms-engine sends.

Communication Log

Track all interactions with customers.

List communications:

Log a communication:

Fields: - subject, summary

Logging a communication automatically updates the customer’s last_contacted_at timestamp.

Archived customers cannot accept new manual CRM communication entries.

Automatic capture provenance: CRM timelines now distinguish manually logged items from comms-engine capture. Auto-captured rows show provenance such as capture source/mode, linkage basis, and optional linked deal/activity ids. Messages that cannot be linked safely do not guess silently; they stay in a review queue until an operator resolves them.

Capture review queue:

Use the Communications tab in CRM to review unresolved inbound captures. The queue shows sender/recipient metadata, the captured preview, and any candidate customer/contact matches from the comms engine. When you resolve one, pick the correct customer and optionally add contact, deal, or activity context. The resulting CRM timeline item records that the final link came from operator review.

Use the Risk & Health tab in CRM to review the same capture exceptions inline when you are already working in CRM. The queue shows sender/recipient metadata, captured preview, candidate counts, and matches; the resolution modal lets you link the customer, contact, deal, or activity without jumping to another route.

List customer conversations (threaded view):

Returns comms engine conversations grouped by thread, with message count, last message timestamp, assigned rep/group, and channel protocol. Filter by status (open, closed, archived).

Deals (Sales Pipeline)

Deals track sales opportunities through the pipeline.

List deals (pipeline view):

The CRM pipeline tab now uses this endpoint as a paged workspace instead of a hidden all-deals preload. Dashboard pipeline cards remain tenant-wide, while the table rows below show only the current stage/search/page slice.

Customer and deal owners stay visible in the pipeline and customer views. You do not need to reopen an edit form to see who currently owns follow-up on an account or opportunity.

Create a deal:

Fields: - name (required) – deal title - value_cents – non-negative deal value in cents - expected_close_date - notes

Auto-transition: If you create a deal with a value > 0 for a customer in prospect stage, the customer automatically moves to qualified.

Archived customers cannot accept new deals. The backend rejects mismatched product/plan combinations, so a Meridian deal cannot quietly convert on an RMM plan. The shared CRM UI now requires product selection during deal creation, keeps the optional plan picker scoped to that same product, and shows the product as a locked field during edit so operators do not accidentally mutate the commercial boundary.

Deal owner stays visible after creation. The pipeline table and customer workspace show the current owner so managers can spot ownership gaps without reopening the edit form.

Edit a deal:

Open deals can update core pipeline fields. Closed deals only allow updates to notes and closed_reason. Archived deals cannot be edited. The product itself is a commercial boundary and cannot be changed after create; open a new deal if the sold product changes.

Archive a deal:

Requires keystone.crm.delete permission and a reason. Archive removes the deal from the active pipeline while keeping history. Converted or closed_won deals cannot be archived.

Delete a deal:

Hard delete is only allowed after archive, and converted or won deals remain protected.

Advance deal stage:

• qualified: 20%
• demo: 40%
• proposal: 60%
• negotiation: 80%

Stage advancement is now backend-driven workflow automation, not just a stage label change. The transition queues a durable automation run that can create seller follow-up and finance handoff activities, retries safely through the scheduler when side effects fail, and records the automation run id/status in the audit trail. The CRM activity queue refreshes so the generated work becomes visible in the normal next-action surfaces.

Close a deal:

Body: { "outcome": "won" | "lost", "reason": "optional reason" }

Closing a deal as “won” automatically transitions the customer to customer lifecycle stage.

Convert a deal to subscription:

This is the full conversion workflow in one call: 1. Creates the product-scoped subscription for the customer on the specified plan 2. Closes the deal as closed_won 3. Transitions the customer to customer lifecycle stage

Fails if the plan does not belong to the deal’s product or if the customer already has a subscription for that same product.

Trial plans create a trial subscription instead of starting billed service immediately. The subscription stores a contract snapshot from the sold plan so downstream product enforcement does not drift when plan defaults later change. Conversion also emits the same product_contract.changed signal used by billing subscribe/change-plan flows, so downstream products can refetch the stable contract surface immediately.

In the shared CRM UI, new-deal, edit, and convert flows all keep plan search product-scoped. Convert/edit flows use searchable plan selectors, and the convert modal shows the deal’s locked product before the operator chooses the sold plan.

CRM Dashboard

Returns: - total_customers – total count - by_lifecycle_stage – breakdown by stage - at_churn_risk – customers with health_score < 30 - pipeline_value_cents – total value of open deals - weighted_pipeline_value_cents – value weighted by close probability - active_deals – count of non-closed deals - recent_communications – communication count in last 7 days

Archived customers are excluded from dashboard customer totals, and archived deals are excluded from pipeline metrics.

The “Customers at Churn Risk” panel is a highlight list of up to 20 currently critical accounts, not a full tenant export. Use the Customers tab when you need the complete filtered account set.

Forecasting & Pipeline Intelligence

The Forecasting tab is the manager surface that sits above the dashboard cards:

Use it when you need server-side, assignment-aware answers to questions like: - what is each rep’s open and weighted forecast? - which open deals are overdue against expected close date? - how old is the current pipeline? - what is the won/lost trend over the last 30, 90, 180, or 365 days?

The owner filter changes the server-side report itself, not just the visible rows in the browser. The tab shows: - summary forecast metrics - accountability by owner - pipeline aging buckets - day-level win/loss trend