🛠️ Build Playbook · Prepared 2026-04-14 · For Robert

📊 HCP Reports Build Playbook

Micro-steps to pull the three priority reports inside Housecall Pro. Honest upfront: I have not seen the HCP UI myself, so each report shows the likely path to try first and a fallback if the UI does not expose it. Fill in the blank lines as you click, so the next person using this doc has confirmed paths. Rate limit on any API fallback: 2 seconds between calls, never skip.

🚦 Pre-Flight — Do These Once Before Any Report

🔑 Log into BSP HCP. URL: — fill in after first login — · Credentials: — from memory/reference-hcp-export-location.md or ask Kalen —. Ashton has no access. You and Kalen are the only BSP HCP admins.
🔎 Confirm customer count. Navigate to Customers (sidebar). Note the total shown. Compare to our export (4,271). If HCP UI shows 4,771, we need a second export with the correct filter to reconcile.
🧭 Find the Reports menu. Kassidy and Ashton both said HCP reports are per-employee and built manually. Try: top nav → Reports OR sidebar → Reports OR Settings → Reports. Document the path in the blank below: — Reports menu location —
📥 Verify export format options. When viewing a report or customer list, look for CSV / XLSX export buttons. Note: — formats available —
🔁 Check if HCP has a public API you can use in parallel. HCP has a Developer API (docs.housecallpro.com). If yes, the API is faster for recurring pulls than re-running a report every time.

🎯 Report 1 — Customer 360 Lookup by Phone

P1 · This week

The biggest operational unlock. When Ashton picks up a call, he types a phone number and sees: name, LTV, last service + tech, last 3 jobs, open estimates, warranties, membership, Do Not Service flags, address.

👉 Click Path (Try HCP UI First)

1🔍 Open the top search bar in HCP

HCP typically has a persistent search bar at the top of the app. Paste a known test phone number (use (913) 302-7665 — Barbara Boyle from the recent list).

2📇 Select the matching customer profile

If it matches, a customer card should appear. Click it. Note what you see on that default view.

3📸 Screenshot the default customer profile view

Capture every field HCP shows by default. Compare against the wish list below. Note the gaps.

📤 Required Output Fields (the wish list)

Field	Status
Name + primary phone + alt phone + email	✓ / ✗
Customer since date	✓ / ✗
Lifetime value	✓ / ✗
Last service date + tech	✓ / ✗
Last 3 jobs (date · type · revenue · tech)	✓ / ✗
Open estimates (count + total value)	✓ / ✗
Active warranties (service + expiration)	✓ / ✗
Membership status	✓ / ✗
Do Not Service / complaint flags	✓ / ✗
Service address (if different from billing)	✓ / ✗

⚠️ Fallback (likely path): HCP's default customer view probably does NOT show all 10 fields in one screen. If any are missing, the solution is Nexus Customer 360 endpoint. I build a Python script that hits HCP API /customers/{id}, /customers/{id}/jobs, /customers/{id}/estimates, aggregates into one JSON response, and renders it as a lookup page at morpheus.callbrightside.com/customer/{phone}. Ashton hits one URL, one screen. Estimated build: 4-6 hours.

✅ Verification: Type (913) 302-7665 (Barbara Boyle) into whichever path you build. Confirm her name, last service, and any open estimates appear within 3 seconds of entry.

🔥 Report 2 — HCP Open Estimates (Ashton-facing)

P1 · This week

The HCP parallel to our ST Estimate Recovery Engine. HCP-only customers still have open quotes. Same HOT / WARM / COLD 0-7 / 8-30 / 30+ day buckets.

👉 Click Path (Try HCP UI First)

1📑 Navigate to Estimates section

Sidebar → Estimates (or top nav → Estimates). Note exact location: — path —

2🎛️ Filter by Status = Open / Pending / Sent

HCP estimate statuses differ from ST. Try filtering to anything that is NOT Accepted / Sold / Declined. Document the status values HCP uses: — statuses —

3📅 Sort by Modified Date descending

Newest first so the hot ones surface. If the column is Created Date, use that instead.

4💾 Export to CSV if available

Look for Export button, top-right of list view typically. Download and open in Excel / Google Sheets.

5🪣 Add age buckets

In Excel: new column =IF(TODAY()-B2<7,"HOT",IF(TODAY()-B2<30,"WARM","COLD")). Replace B2 with the modified-date column.

6🏷️ Flag Pure-HCP vs Migrated

If you already have the Segment A list of 247 Pure-HCP customers (CSV on VM at /documents/hcp_segment_A_pure_hcp_reengagement.csv), VLOOKUP on customer ID to mark which open estimates belong to ghost customers. Those go to the top of the call list — they have no ST equivalent.

⚠️ Fallback: If HCP does not have an Open filter, use the Customers list, filter by Has Active Estimate = Yes, export, then manually split by age in Excel. OR I build a Nexus pull via HCP API /estimates?status=open and drop a CSV to /documents/hcp_open_estimates_tracking.csv nightly. Same pattern as the ST tracker CSV we shipped this morning.

✅ Verification: Row count should roughly match ST's 1,749 Open estimates if migration was 1-to-1. Expect HCP-only to be smaller (247 Pure-HCP customers × likely <1 estimate per = maybe 100-200 open estimates in HCP).

🛡️ Report 3 — Do Not Service List

P1 · Before any email send

Mandatory before we send a single email to the HCP segments. Customers flagged DNS must be excluded from every campaign. Missing this = legal / trust risk.

👉 Click Path (Try HCP UI First)

1🧑 Navigate to Customers section

Sidebar → Customers.

2🚫 Apply Do Not Service filter

Most CRMs have a DNS or Do Not Service toggle on customer records. Try: Filters → Do Not Service = Yes, OR Tags contains "Do Not Service" / "DNS" / "Fire Customer". Note exact path: — DNS filter path —

3💾 Export list

CSV export with at minimum: Customer ID, Name, Phone, Email, DNS reason (if field exists), date flagged, who flagged.

4📋 Save to a restricted location

VM path: /opt/nexus/nexus/scripts/output/hcp_do_not_service.csv. Do not post this to any public URL. Reference-only for campaign exclusion.

5🔁 Cross-reference against ST's DNS flag

Some DNS customers may exist in both systems with different flag statuses. Take the union of both — if flagged DNS in either system, exclude from every campaign.

⚠️ Fallback: If HCP has no native DNS field, the flag may live in Tags or Notes. Grep the export CSV for DNS, DO NOT SERVICE, FIRE, NEVER CALL, BAD CUSTOMER and pull those into a manual exclusion list. Kalen or Ashton reviews the edge cases.

✅ Verification: Merge-check against the Segment A + B + C email lists we built. No DNS customer should appear in any outbound email audience. If any do, they get removed before send.

📊 Priority 2 — Management Visibility (next 1-2 weeks)

Lighter instructions. Each of these is a saved HCP view or filter you build once, then share with the team.

💰 Report 4 · HCP Revenue by Month + Service Type

HCP Reports → Sales / Revenue (if it exists)
Group by Month and Service Type
Export monthly
Fallback: HCP API /invoices?completed_after=X&completed_before=Y, aggregate in Nexus

🔧 Report 5 · HCP Revenue by Technician

HCP Reports → Technician Performance
Filter by date range, group by Technician
Export CSV · compare to Ramp COGS per tech

🎯 Report 6 · Close Rate (Estimates sold / Estimates total)

HCP Estimates list · Status counts: Sold / Declined / Open
Math: Sold / (Sold + Declined) for close rate
Compare to our ST 39.2% figure — if wildly different, that tells us something about tech or customer behavior

🏆 Report 7 · Lifetime Value Distribution (Membership cohort)

Customers list · sort by LTV descending
Filter LTV >= $5,000
Compare count to our Segment B (277 customers from combined HCP+ST)
Kalen uses this to approve the membership pitch cohort

📡 Report 8 · Lead Source Performance (HCP era)

Customers list · group by Lead Source field
Expect 52% blank — document the blank count for Stephanie
Match to ST lead source categories where possible

😴 Report 9 · Dormant Customer List (Audrey email source)

Customers list · filter: Last Service Date < 12 months ago · LTV > $500 · Marketable (not DNS)
Feed Audrey for cold-bucket mass email (Segment C template)

🏢 Report 10 · Commercial vs Residential Breakdown

Customers list · group by Customer Type
Revenue total per bucket · avg ticket
Kalen uses this for commercial stage-1 scoping

⏳ Priority 3 — Future / Strategic

🗓️ Report 11 · Warranty Expiration Calendar

Service History filter by Warranty End Date · flag next-90-day expirations · Ashton or Audrey outreach

🤝 Report 12 · Nick Welty Referral Performance

Tag filter Inspector.com referral · revenue · avg ticket · discount dollars applied. Nick wants this documentation per Apr 1 partnership agreement.

🔍 Report 14 · Cross-System Match Health (Nexus-only)

Quarterly. Unique HCP IDs vs unique ST IDs vs overlap %. Nexus job — not HCP.

📉 Report 15 · Data Quality Audit

Customers list · filter blank Lead Source / missing phone / missing email · list for backfill or acceptance.

✅ Session Success Criteria

🔎 HCP Reports menu location documented
📱 Customer 360 view tested with Barbara Boyle phone, gaps noted
📑 HCP Open Estimates export done and bucketed HOT / WARM / COLD
🚫 Do Not Service list exported and stored at /opt/nexus/nexus/scripts/output/hcp_do_not_service.csv
🔢 Customer count reconciled: does HCP UI show 4,271 or 4,771?
📧 Email to Ashton sent listing the three reports, per meeting action item

🆘 Escalation Paths

Problem	Path
HCP UI does not have a filter I need	Note it, move on. Nexus API + script is the fallback for any missing native view.
API rate limit hit	Increase `time.sleep()` to 3s. Never skip rate limit. Robert's IP has been blocked twice.
Export CSV is malformed	Try XLSX export instead. Convert to CSV locally with `xlsx2csv`.
Customer count discrepancy persists (4,271 vs 4,771)	Ping Ashton, Kalen. Might be BSP vs 100 Year HCP confusion. Also verify filters — some HCP views default to "active customers only."
Stuck on UI location of Reports menu	Intercom chat button (bottom right in most HCP installs). HCP support can point at it in 5 minutes.

Live at https://morpheus.callbrightside.com/documents/BSP_HCP_Reports_Build_Playbook.html. Paired docs: HCP Executive Brief · HCP Intelligence Report · Audrey Email Brief · Estimate Recovery Engine. Fill the blanks in this page as you click through HCP and re-save it — the next person using this gets confirmed paths, not guesses.