Set up customer health

Customer health setup is available only to selected Business workspaces in the private beta. It is not generally available. Workspace owners and admins can save settings. Other members have read-only access.

Before you begin

You need:

• A Business workspace included in the reviewed private beta.
• A declared tracking-plan group that represents a customer account.
• A stable known user_id for each person you want to associate with an account.
• At least one event that represents successful product adoption or value.
• A trusted way to record lifecycle changes.

The setup page shows an unavailable state if the plan or operator rollout does not allow activation. Saved intent cannot widen the rollout policy.

1. Declare the account group

Open Groups and declare one group for the customer account, such as organisation. Then send the stable account identifier with the same event as the known user identifier:

{
  "user_id": "user_42",
  "$groups": {
    "organisation": "account_acme"
  }
}

Open Customers, then Setup, and choose that declared group as the account group.

The account identifier is the source of identity. Keep it stable even if the company name changes. leadmaps never creates an account from IP data, device data, an email address or domain, or anonymous browsing behavior.

2. Define product value events

Add the events that represent successful adoption for your product, such as a project created, report exported, or teammate invited event. Use the exact event name already sent by your tracking plan and give it a readable label.

Choose relative importance only to express which configured value events matter more to your product. It does not turn an event into lifecycle truth and does not override missing evidence.

3. Choose the review cadence

Choose the comparison rhythm that fits normal account usage:

• Weekly pattern.
• Every two weeks.
• Monthly pattern.

leadmaps starts bounded account refreshes each day, and a trusted lifecycle change refreshes the affected account immediately. A very large workspace can finish across later scheduled passes. The cadence controls the comparison window, not event collection frequency.

4. Add trusted lifecycle truth

Observed browser behavior cannot confirm cancellation or churn. Use one of the supported trusted paths:

• Owner or admin correction. Open a customer account, choose a lifecycle change and its effective time, then choose Record change.
• Authorized server event or API. Use a workspace-scoped server credential with the required write access and a unique idempotency key for each logical change. A repeated retry returns the stored result. Reusing the key for different facts is rejected.
• HubSpot or Pipedrive. Connect the CRM with Customer health and lifecycle access, map a stable account identifier, then map selected company or deal statuses to lifecycle changes. The CRM remains the system of record.

Late and out-of-order lifecycle updates stay visible in history. An older effective update cannot replace a newer effective state. A dashboard correction by an owner or admin takes precedence when two trusted sources assert different facts for the same effective time.

The beta dashboard does not include a customer-lifecycle CSV uploader. The general event CSV importer imports analytics events and is not a replacement for a trusted lifecycle integration.

5. Enable and verify

Enable customer health and choose Save settings. Then verify:

1. The Customers list contains only accounts whose identifiers you explicitly supplied.
2. Member counts match the known users associated with each account.
3. Accounts with missing activity show limited evidence instead of a guessed risk state.
4. A test lifecycle change appears in Trusted account state with the correct source and effective time.
5. A repeated test update does not create a duplicate timeline entry or duplicate automation.

Remove test lifecycle data only through the approved workspace test-cleanup process. Lifecycle history is intentionally append-only in normal product use.

Permissions

Role or credential	Read customers	Change setup	Record lifecycle	Refresh now	Manage automations
Owner	Yes	Yes	Yes	Yes	Yes
Admin	Yes	Yes	Yes	Yes	Yes
Member	Yes	No	No	No	No
Viewer	Yes	No	No	No	No
Authorized workspace API credential	According to its server-enforced scope	Admin scope only	Required write scope only	Admin scope only	Admin scope only

Changing a control in the browser cannot grant additional permissions, widen the private beta, or change the workspace plan.

Troubleshooting

The workspace says customer health is unavailable

Confirm the workspace is on Business and has been selected for the private beta. An owner or admin can contact support to request consideration. General availability has not been enabled.

The account group is missing

Declare it under Groups first. Customer health rejects an undeclared group when activation is requested.

No accounts appear

Confirm the same tracked event contains both a stable user_id and the selected $groups value. Anonymous activity alone cannot create a customer account.

Lifecycle import is not updating

Check that the CRM connection uses Customer health and lifecycle access, the account and status fields still exist, and every provider value you expect has an explicit lifecycle mapping. Reconnect if the provider says the saved authorization needs attention.