HVAC Lead Finder Support: Install, Activate, and Use the App
Step-by-step guide for installing HVAC Lead Finder (standalone PHP or WordPress plugin), activating your license, configuring Google Places and Anthropic API keys, running your first lead search, and resolving common issues.
Quick Start: What You Bought
Every tier (Starter, Professional, Agency) ships in two formats — both included with every purchase. Use whichever fits your hosting setup. Your HVAC Lead Finder license key works in both. New here? See how the app works end-to-end.
Standalone App: Best for cPanel and Shared Hosting
A self-contained PHP/MySQL application installed in its own folder or subdomain. Includes a Super Admin panel, company accounts, lead search, homeowner tools, AI analysis, CRM, notes, follow-ups, exports, and logo upload. The full feature set is available subject to your license tier.
- Install location example:
/hvac-leads/ - Super Admin login:
/hvac-leads/admin/ - Company user login:
/hvac-leads/login.php - Filename:
hvac-lead-finder-standalone-{tier}.zip
WordPress Plugin: Best for WordPress Site Owners
Installs inside WordPress and adds an HVAC Leads admin menu. Settings, Dashboard, license activation, and the Anthropic connection test are fully working in v4.0. The lead search, lead list, and homeowner views are placeholders in this build and will arrive in v4.1.
- Install from Plugins → Add New → Upload Plugin
- Settings path: HVAC Leads → Settings
- Data stored in WordPress tables prefixed
hlf_ - Filename:
hvac-lead-finder-plugin-{tier}.zip
System Requirements (Hosting, API Keys, License)
Hosting Requirements (PHP, MySQL, cPanel)
- PHP 8.1 or newer (8.4 recommended).
- MySQL 5.7+ or MariaDB 10.3+.
- Apache or LiteSpeed (cPanel hosting works out of the box).
- HTTPS enabled.
- For standalone: cPanel, phpMyAdmin, or SSH access.
- For plugin: WordPress 6.0+.
Required API Keys (Google Places, Anthropic)
- Google Places API — required for commercial search. ($200/mo free credit covers most users.)
- Anthropic API — required for AI features. ~$0.01–$0.03 per lead.
- ATTOM Property API — optional, Professional/Agency only.
- Regrid API — optional, Professional/Agency only, free tier available.
License Key Requirements
- License key required at every tier (sent in your purchase receipt).
- License Manager Consumer Key + Secret (also in your receipt) so the app can validate against hvacleadfinder.com.
- Activations: 1 site for Starter and Professional, 5 sites for Agency.
- Lifetime use, no recurring fee.
How to Install HVAC Lead Finder (Standalone App)
Follow these nine steps to install the standalone PHP application on cPanel, LiteSpeed, or any standard PHP host. Total time: about 20 minutes. For an overview of what the app does after install, see How It Works.
Step 1: Upload the App Folder to Your Host
Upload the entire hvac-leads/ folder from your tier zip to your hosting account. A common cPanel path is public_html/hvac-leads/.
Step 2: Create a MySQL Database in cPanel
In cPanel, open MySQL Databases, create a database, create a database user, and assign the user ALL PRIVILEGES for that database.
Step 3: Import install.sql via phpMyAdmin
Open phpMyAdmin, select the new database, click Import, choose install.sql from the unzipped folder, and click Go.
Step 4: Edit Database Settings in config.php
Open includes/config.php and update the database constants.
define('DB_HOST', 'localhost');
define('DB_NAME', 'your_database_name');
define('DB_USER', 'your_database_user');
define('DB_PASS', 'your_secure_password');Step 5: Verify Folder Permissions for Uploads and Exports
Make sure uploads/, uploads/logos/, and exports/ are writable. Standard 755 folder permissions are usually enough on cPanel.
Step 6: Log In as Super Admin and Change the Default Password
Go to /hvac-leads/admin/. The default login created by the install SQL is:
Username: admin Password: ChangeMe123!
Change this password immediately using the Change Admin Password form on the same page.
Step 7: Activate Your HVAC Lead Finder License Key
In the Super Admin panel, find the License card. Paste your license key and the License Manager Consumer Key + Secret from your purchase receipt. Click Activate. The active tier label will appear once activation succeeds — see the License section below for full details.
Step 8: Add Google Places and Anthropic API Keys
In the same Super Admin panel, paste your Google Places key and Anthropic key. Add ATTOM or Regrid only if your tier includes the homeowner module (Professional or Agency).
Step 9: Create Your First HVAC Company Account
Use the Create HVAC Company Account form to set up your first company and owner user. The owner logs in at /hvac-leads/login.php with the credentials you set.
How to Install the HVAC Lead Finder WordPress Plugin
Use this option to install HVAC Lead Finder inside WordPress. The plugin filename matches your tier: hvac-lead-finder-plugin-starter.zip, hvac-lead-finder-plugin-professional.zip, or hvac-lead-finder-plugin-agency.zip.
Step 1: Upload the Plugin ZIP to WordPress
Go to WordPress Admin → Plugins → Add New → Upload Plugin. Upload the tier zip you downloaded and click Install Now.
Step 2: Activate the Plugin in WordPress
Click Activate Plugin. Activation creates the plugin database tables (hlf_*) and seeds default settings. Plugin data is preserved on deactivation; only an explicit Delete removes it.
Step 3: Open the HVAC Leads Admin Menu
After activation, an HVAC Leads menu appears in wp-admin. Open the Dashboard first, then go to HVAC Leads → Settings.
Step 4: Activate Your License Key in WordPress
The Settings page opens with the License card at the top. Paste your license key, then scroll to License Validation Credentials and paste your Consumer Key + Secret from your purchase receipt. Save, then click Activate License. The active tier appears in the card header.
Step 5: Enter API Keys and Business Info
Add your Google Places key, Anthropic key, business name, phone, and website. Add ATTOM or Regrid keys only if your tier (Professional or Agency) includes the homeowner module.
Step 6: Test the Anthropic API Connection
Click Test Connection next to the Anthropic key. A green checkmark confirms WordPress can reach the Anthropic API from your server.
Step 7: Understand What Works in Plugin v4.0
The plugin v4.0 includes a working Settings page, working license activation, working Dashboard with live stats, working tooltips, and the database foundation. The lead search, lead list, and homeowner views still show placeholders in v4.0 and finish in v4.1 (free upgrade for existing buyers). For full features today, use the standalone app instead.
wp_options under the key hlf_settings. Lead data lives in WordPress tables prefixed with your site's database prefix — wp_hlf_leads, wp_hlf_campaigns, wp_hlf_homeowner_leads, and related notes/campaign tables.License Key Activation: Unlock Your Tier Features
Every HVAC Lead Finder tier requires a valid license. Activation unlocks the features included with your tier and confirms the install is authorized. See the full feature breakdown on the pricing page.
What You Received in Your Purchase Email
- License key — format:
XXXX-XXXX-XXXX-XXXX - Consumer Key — format:
ck_... - Consumer Secret — format:
cs_... - Both download links (standalone and plugin)
The Consumer Key and Secret are the same for every customer — they're your install's way of asking hvacleadfinder.com to validate your license. Keep them with your other credentials.
What License Activation Does
- Validates your license against hvacleadfinder.com
- Reads your tier (Starter, Professional, or Agency) from the validation response
- Unlocks the matching features in your install
- Caches the result for 12 hours so the app keeps working even if our validation server is briefly unreachable
HVAC Lead Finder Tier Feature Comparison
- Starter: Commercial search, AI output, CRM, CSV export. 1 user, 500-lead cap, 1 site.
- Professional: Adds homeowner module (CSV, Regrid, ATTOM), team users up to 5, 5,000-lead cap, 1 site.
- Agency: Adds multi-tenant client management, white-label rebranding, unlimited leads/users, 5 sites.
If a Higher-Tier Feature Is Locked
Each downloadable zip has a baked-in tier ceiling. A Starter zip can't unlock Professional features even with a Professional license — you need to download the Professional zip and reinstall over the existing one. Your data stays in the database.
Log in to your hvacleadfinder.com account to download a different tier zip after upgrading.
API Key Setup (Google Places, Anthropic, ATTOM, Regrid)
| API key | Used for | Required? | Common support issue |
|---|---|---|---|
| Google Places API | Commercial business search — names, addresses, phone numbers, ratings, websites. | Required for commercial search. | REQUEST_DENIED usually means Places API is not enabled in Google Cloud, billing isn't active, or key restrictions don't match the install URL. |
| Anthropic API | AI scoring, opportunity analysis, scripts, outreach copy, conversation starters, pain points, objection handlers. | Required for AI features. | Usually a missing/expired key, no credits on the Anthropic account, or outbound HTTPS blocked by host. |
| ATTOM Property API | Direct homeowner property pulls by ZIP and year built. Returns characteristics, not owner names. | Optional — Professional/Agency tiers only. | No homeowner data usually means no key, missing tier, plan limit, or bad ZIP/year combination. |
| Regrid API | County parcel data for the County Search homeowner workflow. | Optional — Professional/Agency tiers only. | Check the key, the county's data availability, and your monthly quota. Free tier is 1,000 parcels/month. |
How to Use HVAC Lead Finder (Operating Manual)
The operating manual once setup is complete. Sections marked with a tier badge require that tier or higher.
How to Find Commercial HVAC Prospects
- Open Find HVAC Leads (standalone) or Find Commercial (plugin v4.1+).
- Select a state.
- Enter a city for tighter local targeting.
- Pick a building category and building type.
- Set the maximum results (capped at 60 per search).
- Choose whether to run AI analysis during the search.
- Start the search — the campaign runs in the background.
- Review results sorted by HVAC score.
How to Find Homeowner Prospects
- Open Find Homeowners or Homeowner Leads.
- Choose a source: County Search, CSV Import, or ATTOM Data.
- For ATTOM: enter ZIP, year-built range, square footage filters, max results.
- For CSV: download the template, fill in your data, upload.
- For County: select state and city, set year-built range.
- Run AI analysis to score urgency and HVAC opportunity.
- Review records, urgency labels, and AI-generated outreach copy.
How to Use the AI Scripts and Outreach Copy
- Sort leads by HVAC score and start with the highest.
- Read the service angle and score reasoning before calling.
- Use conversation starters to open the call naturally.
- Use the call script as a personalized starting point — bring your own voice.
- For mailing: use door hanger copy, mail letter, or email template as written or edit lightly.
- Log objections and outcomes after each call.
- Set a follow-up date immediately after every meaningful contact.
How to Manage HVAC Leads in the Built-In CRM
- Filter by score, status, urgency, campaign, or search term.
- Update lead status as work progresses (new → attempting → connected → proposal → won/lost).
- Log call outcomes (no answer, voicemail, spoke to owner, callback scheduled, not interested).
- Add notes after every meaningful interaction.
- Set follow-up dates so nothing falls through the cracks.
- Export to CSV for spreadsheets, sales reps, external CRMs, or client delivery.
How Agencies Deliver Lead Packages to HVAC Clients
- Create a company account for each HVAC client (standalone Super Admin, or plugin Companies page).
- Upload each client's logo so they see white-label branding when they log in.
- Run a small starter campaign before pitching a full lead package.
- Deliver CSV exports with AI summaries attached.
- Use the notes/follow-up system to track campaign progress per client.
- White-label the entire app with your own logo, colors, and footer attribution (Branding settings).
How to Get Better HVAC Lead Quality
- Use a specific city instead of an entire state.
- Start with high-HVAC-demand building types: restaurants, medical, hotels, gyms, churches, warehouses.
- For homeowners, target homes built 1970–2005 — old enough to need replacement, recent enough for working contact records.
- Don't rely on AI score alone. Verify website, reviews, and business activity.
- Call hot leads quickly — same-day call beats a perfect script next week.
- Use exported lists for retargeting ads, email sequences, and direct mail.
HVAC Lead Finder Troubleshooting Guide
Common errors and their fixes. Still stuck after working through the table? Contact support with the details listed in the support checklist below.
| Problem | Most likely cause | What to do |
|---|---|---|
| Blank page or 500 error | PHP fatal error, wrong database credentials, missing table, or permission issue. | For standalone, append ?debug=1 to the URL to see the PHP error. Check includes/config.php credentials and your hosting error log. |
| License says "Could not reach hvacleadfinder.com" | Missing Consumer Key/Secret, wrong values, or your host blocks outbound HTTPS to hvacleadfinder.com. | Re-check your purchase email and paste the Consumer Key + Secret exactly. If still failing, ask your host to whitelist hvacleadfinder.com. |
| License says "valid but no tier associated" | The product on hvacleadfinder.com is missing the hlf_tier meta tag (admin error on our side). | Contact support with your license key. We'll add the missing meta within 24 hours. |
| Feature is locked even after activation | Your zip's tier ceiling is below your license tier (e.g. Starter zip + Professional license). | Log in to your hvacleadfinder.com account and download the matching tier zip. Reinstall over the existing files. Your data stays in the database. |
| Access denied for database user | Wrong DB credentials in config.php, or user lacks privileges. | Reset the database user password in cPanel, update config.php, confirm ALL PRIVILEGES on the correct database. |
| Search returns no businesses | Google Places API issue, location too narrow, or key restrictions. | Try a broader city/category combo. Confirm Places API is enabled and billing is active in Google Cloud Console. |
| REQUEST_DENIED from Google | Billing disabled, wrong API restriction, Places API not enabled, or invalid key. | Open Google Cloud Console → APIs & Services → enable Places API. Confirm billing. Allow the correct domain in key restrictions. |
| AI analysis fails | Anthropic key missing, invalid, out of credits, or outbound HTTPS blocked. | Check the key in console.anthropic.com, confirm credit balance. In the plugin, click Test Connection. |
| Login keeps returning to login page | Sessions/cookies issue or inactive user/company. | Clear browser cookies, confirm PHP sessions work, ensure the company and user are both marked active. |
| Logo will not upload | Folder permissions or unsupported file type. | Check uploads/logos/ permissions. Try a small PNG/JPG/SVG under 2MB. Hard-refresh after upload. |
| CSV import fails | Wrong columns, malformed rows, or upload size limit. | Use the provided CSV template. Test with 5 rows first. Increase upload_max_filesize in PHP if needed. |
| Plugin page says "Coming in v4.1" | The plugin v4.0 ships those views as placeholders. | Use the standalone app for full features today, or wait for v4.1 (free update for existing buyers). |
Frequently Asked Questions About HVAC Lead Finder
Do I get both formats with one purchase?
Yes. Every tier includes both the standalone app and the WordPress plugin. Your license key works in both. Use whichever fits your hosting.
Do I need API keys to use HVAC Lead Finder?
Yes. Google Places for commercial search and Anthropic for AI features are required. ATTOM and Regrid are optional, Professional/Agency only.
Will HVAC Lead Finder generate leads automatically?
No. You choose the market and run searches. The tool finds and analyzes prospects; outreach and follow-up are still your job.
Can agencies use HVAC Lead Finder for HVAC clients?
Yes — the Agency tier is built for that. Manage multiple HVAC clients from one install, white-label the app with your branding, and resell client logins.
Where is my HVAC Lead Finder data stored?
Always on your own server. Standalone uses its own database. Plugin uses your WordPress database (hlf_* tables and wp_options). Nothing leaves your server except the API calls you authorize.
How do I upgrade my HVAC Lead Finder tier?
Pay the difference at hvacleadfinder.com, download the higher-tier zip, reinstall over the existing files. Your license is upgraded automatically and your data stays intact.
Will the WordPress plugin slow down my site?
No. The plugin loads its assets only on its own admin pages. Front-end visitors don't trigger any plugin code.
What is the refund policy for HVAC Lead Finder?
Contact us within 30 days of purchase if the product doesn't work for you. We refund installs that fail validation or hit hosting incompatibilities we can't resolve.
Before You Contact Support
Working through this checklist resolves about 80% of issues. If you still need help, the second card lists what to include in your support request so we can solve it on the first reply.
Pre-Support Diagnostic Checklist
- Confirm whether you installed standalone or plugin.
- Note your tier (Starter, Professional, or Agency).
- Confirm PHP version is 8.1 or newer.
- Confirm your license shows as activated in Settings.
- Confirm Google Places and Anthropic keys are saved.
- Try a small test search before reporting a search problem.
- Screenshot the exact error message.
- Check your hosting error log.
- For standalone, append
?debug=1to the URL — it surfaces the underlying PHP error.
What Information to Include in Support Requests
- Site URL or app URL.
- Standalone or plugin, and which tier.
- PHP version and hosting provider.
- Screenshot of the error or the page.
- Which API is involved (Google, Anthropic, ATTOM, Regrid).
- For database errors, the error text — never the password.
- Last few lines of your hosting error log if you can access it.
Security reminder: Never email API keys, database passwords, WordPress admin passwords, cPanel passwords, or License Manager Consumer Secrets in plain text. If we need a credential to debug, we'll send a secure form. Open a support request →