AI Lead Scoring for Perfex CRM

Module documentation for installation, configuration, and full feature usage.

This is a Perfex CRM module (not standalone).
Required: Perfex CRM installed and active.

🎉 NEW UPDATE (v1.1)

• Rule engine is now the primary scoring source (no AI required).
• Added scoring profiles with automatic profile detection.
• Added flexible conditions for rules and profiles (field + operator + value).
• Improved score breakdown display in the lead tab.
• AI is optional and used only for insights.
• Better rescoring flow with queue handling and outdated score indicators after rule/profile/label updates.

1. Installation

1. Zip folder name should be ai_lead_scoring (standard Perfex module structure).
2. Go to Setup → Modules.
3. Upload module zip and click Install.
4. Click Activate.
5. Go to Setup → Settings → AI → AI Lead Scoring and configure module settings.

2. Menu & Pages

• Lead Scoring Reports - KPIs, charts, AI usage & cost, recent scores. Go to: Reports → Lead Scoring
• Lead Scores - table view with filters and bulk actions. Go to: Lead Scores under Leads
• Rules - dynamic rule conditions and score points. Go to: Setup → Lead Scoring → Rules
• Profiles - profile matching conditions and priority. Go to: Setup → Lead Scoring → Profiles
• Labels - score range labels (Hot/Warm/Cold defaults protected). Go to: Setup → Lead Scoring → Labels
• Settings - auto-rescore, retry, queue threshold, optional AI insights settings. Go to: Setup → Settings → Configure Features → Lead Scoring

3. Settings

Optional AI Insights

• AI is optional and not required for scoring.
• When enabled, providers include OpenAI, Anthropic, Gemini, Grok, OpenRouter.
• OpenRouter requires custom model name and input/output token pricing.

Automatic Rescoring

• Enable/Disable automatic rescoring.
• Frequency: Daily, Bi-weekly, Weekly, Monthly.
• Retry count, retry delay (minutes), batch size per run.

Lead Data Sent to AI

• Only used for optional AI insights requests.
• Select which standard lead fields are sent.
• Select which lead custom fields are sent.

4. Lead Modal Score Tab

• Shows final score, label, profile, and full score breakdown.
• Breakdown groups conditions by rule name with matched status.
• Shows last scored at and scored by (staff/cron).
• Actions: Score/Rescore Lead, Cancel queued job.
• Optional AI insights actions and admin-only raw JSON debug section (when AI insights enabled).

5. Lead Scores Page

• Columns: Lead, Final Score, Label, Last Activity, Last Scored At, Scored By, Actions.
• Top KPI cards: Total Leads, Scored Leads, Pending Jobs, Unscored Leads.
• Filters via App_table_filter (score/label/staff/source/unscored).
• Bulk scoring/insights use queue processing based on threshold settings.

6. Scoring Rules

• Dynamic condition builder: Field + Operator + Value.
• Supports multiple conditions per rule with AND / OR logic.
• Works with standard lead fields and lead custom fields.
• Score points accept positive and negative values.
• Final score is calculated locally from matched rule points and clamped to 0-100.

7. Scoring Profiles

• Create profile-based scoring setups for different lead segments.
• Set profile priority and automatic profile detection conditions.
• Use profile entry conditions with AND/OR logic.
• Assign rules per profile or apply rules to all profiles.

8. Scoring Labels

• Define label names and score ranges.
• Color per label for UI consistency.
• Default labels Hot/Warm/Cold are undeletable for system stability.

9. Dashboard

• KPI cards with icons.
• Charts: Hot/Warm/Cold donut, score distribution, rescore volume, usage/cost.
• Recent Scores table sorted by latest timestamp first.
• Empty states for no-data charts and lists.

9. Queue, Cron, and Retries

• Manual actions can score instantly; bulk actions use queue based on threshold.
• Cron processes jobs in batches and runs scheduled rescoring.
• When rules/profiles/labels change, scored leads are marked outdated and rescoring can be queued.
• Non-retryable failures (e.g., API key/provider config, quota/billing limits) are marked failed directly.

10. Changelog

Version 1.1.0

• Rule engine is now the primary scoring source (AI not required).
• Added scoring profiles with automatic profile detection.
• Added flexible conditions for rules and profiles (field + operator + value).
• Added detailed score breakdown in lead tab.
• Added optional AI insights generation (separate from score calculation).
• Improved queue-based rescoring and outdated score indicators.

Version 1.0.0

• Initial release.

11. Support

For help with setup, migration, or troubleshooting:
support@maniss.dev